obsidian-mcpx

Extended MCP server for Obsidian — 82 typed tools wrapping the official CLI for full vault control from any MCP client.

Built by AI. This server was designed and implemented by Claude (Anthropic) in collaboration with a human operator. The code, tests, architecture decisions, and this README were produced through iterative AI-human pairing. We believe in transparency about how software is made.

What makes this different

| Server | Tools | Approach | Requires Obsidian | |--------|-------|----------|-------------------| | obsidian-mcp (StevenStavrakis) | 12 | Filesystem | No | | obsidian-mcp-server (marcelmarais) | 4 | Filesystem | No | | @marwansaab/obsidian-cli-mcp | 33 | CLI + escape hatch | Yes | | obsidian-mcpx | 82 | CLI + filesystem fallback | Yes (auto-launches) |

The x stands for extended. Every CLI command is a typed tool — no escape hatch needed. Plus surgical edits, auto-launch recovery, structured errors, and large-content filesystem bypass.

Prerequisites

• Node.js 18+
• Obsidian 1.12.7+ with CLI enabled (Settings → General → Command line interface)
• Obsidian running (or let auto-launch handle it)

Install

npm install -g obsidian-mcpx

Or use directly with npx:

npx obsidian-mcpx

Configure

Claude Desktop (Cowork)

Edit your config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcpx"],
      "env": {
        "OBSIDIAN_CLI_PATH": "C:\\Program Files\\Obsidian\\Obsidian.com"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code (CLI)

claude mcp add obsidian -- npx -y obsidian-mcpx

Or add to .mcp.json in your project root:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcpx"],
      "env": {
        "OBSIDIAN_CLI_PATH": "C:\\Program Files\\Obsidian\\Obsidian.com"
      }
    }
  }
}

Cursor

Go to Cursor Settings (Cmd+Shift+J / Ctrl+Shift+J) → MCP tab → Add Server:

• Name: obsidian
• Command: npx -y obsidian-mcpx

Or add to .cursor/mcp.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcpx"],
      "env": {
        "OBSIDIAN_CLI_PATH": "C:\\Program Files\\Obsidian\\Obsidian.com"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcpx"],
      "env": {
        "OBSIDIAN_CLI_PATH": "C:\\Program Files\\Obsidian\\Obsidian.com"
      }
    }
  }
}

Any MCP client (generic)

The server uses stdio transport. Point any MCP-compatible client at:

npx -y obsidian-mcpx

Platform-specific paths

| OS | OBSIDIAN_CLI_PATH value | |---|---| | Windows | C:\Program Files\Obsidian\Obsidian.com or %LOCALAPPDATA%\Programs\Obsidian\Obsidian.com | | macOS | /usr/local/bin/obsidian (auto-detected, usually don't need to set) | | Linux | ~/.local/bin/obsidian (auto-detected, usually don't need to set) |

OBSIDIAN_CLI_PATH is optional — the server auto-detects on all platforms. Set it explicitly if detection fails.

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | OBSIDIAN_CLI_PATH | auto-detect | Full path to Obsidian.com (Win) or obsidian binary | | OBSIDIAN_AUTO_LAUNCH | on | Set to off/0/false to disable auto-launch |

Features

Auto-launch recovery

If Obsidian isn't running when a tool is called, the server launches it via obsidian:// URI, waits up to 30s for readiness, then retries. Disable with OBSIDIAN_AUTO_LAUNCH=off.

Large content bypass

Content over 4KB bypasses the CLI's IPC (which has buffer limits on Windows) and writes directly to the vault filesystem. Handles .md, .canvas, .json — any extension.

Structured errors

All failures return JSON with typed error codes:

{ "error": "FILE_NOT_FOUND", "message": "File not found", "details": {...} }

Codes: VALIDATION_ERROR, CLI_BINARY_NOT_FOUND, CLI_NON_ZERO_EXIT, CLI_TIMEOUT, OBSIDIAN_NOT_RUNNING, FILE_NOT_FOUND, ERR_NO_ACTIVE_FILE, VAULT_NOT_FOUND, AUTO_LAUNCH_FAILED

Surgical operations

Granular reads/writes without pulling entire files:

• obsidian_read_heading — read body under one heading
• obsidian_read_property — read one frontmatter field as { value, type }
• obsidian_patch_heading — replace/append/prepend under a heading
• obsidian_patch_block — replace content at a ^block-id
• obsidian_find_and_replace — vault-wide find-and-replace with dry-run

Self-documenting

Call obsidian_help() for a full tool index, or obsidian_help({ tool_name: "obsidian_read" }) for per-tool docs.

Tool Inventory (82 tools)

| Category | Tools | |----------|-------| | Files | file_info, files_list, folder_info, folders_list, open, create, read, append, prepend, move, rename, delete | | Daily Notes | daily, daily_path, daily_read, daily_append, daily_prepend | | Tasks | tasks, task | | Search | search, search_context, search_open | | Tags | tags, tag | | Links | backlinks, links, unresolved, orphans, deadends | | Properties | properties, property_set, property_remove, property_read, aliases | | Surgical | read_heading, read_property, patch_heading, patch_block, find_and_replace | | Plugins | plugins, plugins_enabled, plugins_restrict, plugin_info, plugin_enable, plugin_disable, plugin_install, plugin_uninstall, plugin_reload | | Themes | themes, theme_info, theme_set, theme_install, theme_uninstall, snippets, snippets_enabled, snippet_enable, snippet_disable | | Sync | sync, sync_status, sync_history, sync_read, sync_restore, sync_open, sync_deleted | | Publish | publish_site, publish_list, publish_status, publish_add, publish_remove, publish_open | | Workspace | workspace, workspaces, workspace_save, workspace_load, workspace_delete, tabs, tab_open, recents | | Developer | devtools, dev_debug, dev_cdp, dev_errors, dev_screenshot, dev_console, dev_css, dev_dom, dev_mobile, eval | | Bases | bases, base_views, base_create, base_query | | Bookmarks | bookmarks, bookmark | | Templates | templates, template_read, template_insert | | Vault | vault, vaults | | History | diff, history, history_list, history_read, history_restore, history_open | | Outline | outline | | Commands | commands, command, hotkeys, hotkey | | Misc | version, reload, restart, random, random_read, unique, web, wordcount | | Help | help |

Multi-vault

All tools accept an optional vault parameter to target a specific vault by name or ID. If omitted, uses the currently active vault.

Architecture

src/
├── index.ts            # MCP server entry (stdio), routing
├── executor.ts         # CLI exec + large-content bypass
├── errors.ts           # Structured error codes
├── auto-launch.ts      # Auto-launch recovery
├── surgical.ts         # Filesystem-based granular ops
├── help.ts             # Self-documenting help handler
└── tools/
    ├── index.ts        # allTools array
    ├── types.ts        # ToolDef interface
    ├── files.ts        # File CRUD
    ├── daily.ts        # Daily notes
    ├── tasks.ts        # Task management
    ├── search.ts       # Search
    ├── tags-links.ts   # Tags & links
    ├── properties.ts   # Properties/frontmatter
    ├── surgical.ts     # Surgical tool schemas
    ├── help.ts         # Help tool schema
    ├── plugins.ts      # Plugin management
    ├── themes.ts       # Themes & snippets
    ├── sync-publish.ts # Sync & Publish
    ├── workspace.ts    # Workspace & tabs
    ├── dev.ts          # Developer tools
    ├── bases-bookmarks-templates.ts
    ├── vault-history-outline.ts
    └── commands-misc.ts

Development

git clone https://github.com/user/obsidian-mcpx
cd obsidian-mcpx
npm install
npm run build
npm test

How this was built

This project was built through AI-human collaboration using Claude (Anthropic). The human provided direction, tested against a live Obsidian instance on Windows, reported errors, and made design decisions. Claude wrote all code, tests, documentation, and architecture. Tested on Windows 11 with Obsidian 1.12.7+ and Node.js v24. macOS and Linux paths are implemented but not yet field-tested — contributions welcome.

License

MIT

Acknowledgements

• Obsidian team for the Integrated CLI (1.12.7+)
• @marwansaab / obsidian-cli-mcp — structured error codes, auto-launch recovery, surgical read/write tools, and the self-documenting help pattern were adopted from their well-typed MCP server design
• @marcelmarais / obsidian-mcp-server — referenced as a lightweight filesystem-based approach
• @StevenStavrakis / obsidian-mcp — the most popular Obsidian MCP server, referenced for comparison