obsidian-writer-mcp

MCP server for Obsidian vaults - 75 tools for notes, tasks, CRM, and semantic search.

Why this MCP?

Existing MCPs don't scale:

• StevenStavrakis: Timeout on 4000+ notes (no cache, full scan)
• MarkusPfundstein: Requires Obsidian running (not VPS/headless compatible)

obsidian-writer = direct filesystem + SQLite WAL + LRU cache + FTS5 search.

Installation

With Claude Code

claude mcp add obsidian-writer \
  -e OPENAI_API_KEY=sk-... \
  -e ENABLE_EMBEDDINGS=true \
  -s user \
  -- npx -y obsidian-writer-mcp "/path/to/vault"

Without embeddings (no API key needed):

claude mcp add obsidian-writer -s user \
  -- npx -y obsidian-writer-mcp "/path/to/vault"

Manual

npx obsidian-writer-mcp /path/to/vault

Update

npx -y always fetches the latest version. Just restart Claude Code to reload the MCP.

To force reinstall:

claude mcp remove obsidian-writer -s user
claude mcp add obsidian-writer -s user \
  -- npx -y obsidian-writer-mcp "/path/to/vault"

Configuration

Add to your MCP config (.mcp.json or Claude Desktop config):

{
  "mcpServers": {
    "obsidian-writer": {
      "command": "npx",
      "args": ["-y", "obsidian-writer-mcp", "/path/to/vault"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "ENABLE_EMBEDDINGS": "true",
        "ENABLE_AUTO_FEEDBACK": "true",
        "SKIP_SUGGESTIONS": "false",
        "EXPAND_ATTACHMENTS": "true"
      }
    }
  }
}

See .mcp.json.example for all options including similarity thresholds.

Environment Variables

Core

| Variable | Description | Default | |----------|-------------|---------| | VAULT_PATH | Path to Obsidian vault (alternative to CLI arg) | - | | OPENAI_API_KEY | OpenAI API key for semantic search | - |

Features

| Variable | Description | Default | |----------|-------------|---------| | ENABLE_EMBEDDINGS | Enable semantic search (requires OPENAI_API_KEY) | false | | ENABLE_AUTO_FEEDBACK | Auto-record accepted links as feedback | true | | SKIP_SUGGESTIONS | Skip link suggestions in create_* tools | false | | EXPAND_ATTACHMENTS | Expand Excalidraw/images in read_note | true |

Similarity Thresholds

| Variable | Description | Default | |----------|-------------|---------| | SIMILARITY_THRESHOLD_HIGH | Duplicate detection (quasi-certain) | 0.95 | | SIMILARITY_THRESHOLD_MEDIUM | Strong similarity warning | 0.85 | | SIMILARITY_THRESHOLD_LOW | Semantic search minimum | 0.55 |

Internal Defaults (not configurable via env)

• LRU Cache: 500 notes max, 50MB, 10min TTL
• File Watcher: 300ms debounce

Tools (75)

CREATE (9)

| Tool | Description | |------|-------------| | create_ressource | Resource note in 3 - RESSOURCES/ | | create_permanente | Permanent note in 5 - GARDEN/ with compass | | create_fleeting | Fleeting note in CALENDAR/Fleeting/ | | create_area | Area note in 2 - AREA/ | | create_litteraire | Literary note in SOURCES/ | | create_projet | Create project folder + MOC | | create_projet_note | Note in existing project | | create_daily | Daily journal | | create_weekly | Weekly journal |

READ (7)

| Tool | Description | |------|-------------| | read_note | Read note with Excalidraw expansion | | search_notes | FTS5 full-text search (BM25, title boost x10) | | list_mocs | List MOCs (garden/ressources/all) | | list_tags | List valid tags with counts | | get_backlinks | Note backlinks | | get_stats | Vault stats | | get_vault_rules | Vault rules in markdown |

TASKS (13)

| Tool | Description | |------|-------------| | list_tasks | Filtered list (status, priority, due, folder) | | list_overdue_tasks | Overdue tasks | | list_tasks_today | Today's tasks | | list_tasks_this_week | This week's tasks | | tasks_for_project | Project tasks | | tasks_summary | Stats (total, todo, done, overdue) | | eisenhower_matrix | 4 quadrants + 32nd day | | create_task | Create task (emoji format) | | complete_task | Mark done | | uncomplete_task | Unmark done | | reschedule_task | Change due date | | set_task_priority | Change priority | | delete_task | Delete task |

SMART CREATION (10)

| Tool | Description | |------|-------------| | semantic_search | Concept search (OpenAI embeddings) | | find_similar_notes | Similar notes to a given note | | suggest_links | Find relevant notes for linking | | suggest_split | Analyze note for potential split | | suggest_merge | Find merge candidates | | execute_split | Split note into child notes | | execute_merge | Merge two notes | | record_feedback | Record accept/reject on suggestions | | get_learning_stats | Learning stats (Bayesian scores) | | reset_learning | Reset feedback history |

CRM (4)

| Tool | Description | |------|-------------| | create_crm_contact | Create contact | | create_crm_conversation | Create conversation linked to contact | | search_crm | Search CRM | | list_crm_contacts | List all contacts |

AUDIT (4)

| Tool | Description | |------|-------------| | audit_note | Full diagnostic | | find_orphans | Notes without backlinks | | find_unlinked_mentions | Text that should be linked | | find_empty_notes | Empty/near-empty notes |

SYNC CONFLICTS (3)

| Tool | Description | |------|-------------| | detect_sync_conflicts | Scan for Syncthing conflicts | | compare_sync_conflicts | Compare original vs conflict | | resolve_sync_conflict | Resolve (keep/use/both) |

Other tools

• EDIT (1): edit_note (replace, insert after, or append)
• LITTERAIRE (4): append_litteraire, get_active_litteraire, set_active_litteraire
• METADATA (2): set_statut, update_frontmatter
• LINKS & ORG (5): add_compass_link, add_tag, remove_tag, move_note, list_directory
• NAVIGATION (5): list_projects, list_fleeting, list_todos_notes, get_project_context, get_today/get_week
• SUGGESTION (2): suggest_links, transform_to_moc
• VALIDATION (1): validate_note
• EXCALIDRAW (4): create_excalidraw (flowchart/architecture/mindmap/sequence), read_excalidraw_text, list_note_attachments, get_attachment_path

Performance

Request → LRU Cache (hit?) → SQLite Index → Filesystem
              ↑                    ↑
         500 notes            FTS5 + WAL mode
         10min TTL            ~5-10ms queries

• Initial indexation: ~15-20s for 5000 notes
• Incremental updates: <200ms via Chokidar
• Search: ~5-10ms with FTS5

License

MIT