Obsidian MCP连接器

Prerequisites

Requirements

• A folder named exactly Prompts (capital P) at the root of your vault. That's it — no additional plugins required. The prompt renderer runs in-process inside the plugin.

If you use other Templater expressions in the prompt body (e.g. <% tp.date.now() %>), they are passed through verbatim — the MCP server does not evaluate them. Only <% tp.mcpTools.prompt(…) %> declarations and {{arg}} placeholders are processed.

Requirements

• Bun latest (pinned via mise.toml)
• TypeScript 5+

Installation

MCP Connector is available in the Obsidian community plugin store and via BRAT — use either.

Quick setup for clients

The plugin settings expose three Copy config buttons — one per supported client family. Each button copies a ready-to-paste JSON snippet to the clipboard.

Verifying the setup

Once configured, your client should expose 43 MCP tools from this server, plus any prompts you have tagged with #mcp-tools-prompt in a Prompts/ folder at your vault root.

To verify the connection works end-to-end, ask the agent to call get_server_info. A successful response confirms the client can reach the in-process server and the bearer token is correct. For deeper inspection (request/response logs, tool schema inspection without an LLM in the loop), use @modelcontextprotocol/inspector:

```bash npx -y @modelcontextprotocol/inspector

"Server disconnected" after updating from a pre-0.4.9 build

• Symptom: Claude Desktop shows MCP mcp-tools-istefox: Server disconnected; its logs show ECONNREFUSED 127.0.0.1:<port>.
• Cause: pre-0.4.9 builds could fail to release the server port on Obsidian reload/disable and "walk" to the next one (27200 → 27201 → …), so claude_desktop_config.json may point at an old walked port while 0.4.9 now correctly binds the default. 0.4.9 fixes the walk; the stale config is a one-time leftover from the old build, not a recurring issue.
• Fix: fully quit Claude Desktop (Cmd+Q on macOS) and reopen it — Claude Desktop only re-reads claude_desktop_config.json at launch; closing the window or an in-app restart is not enough. With auto-write on (the default) the plugin keeps the config in sync afterward.
• Still failing? Confirm the port in claude_desktop_config.json (http://127.0.0.1:<port>/mcp) matches the port the plugin logs on start (Settings → Open Logs), ensure only one Obsidian vault has the plugin enabled (two instances contend for the port), then fully restart Claude Desktop again.

Building

bun install                    # Install workspace dependencies
bun run check                  # Type-check every package
bun run dev                    # Watch all packages
bun run build                  # Production build

The plugin's main.js is written at the package root (packages/obsidian-plugin/main.js); Obsidian expects that path. Do not move it.

Optional

• Templater — needed only for the execute_template tool. The prompt library works without it.
• Local REST API — needed only for the search_vault tool (DQL / JsonLogic queries). All other tools work without it. [^4]
• Smart Connections — alternative semantic-search backend. The native MiniLM provider works just as well; Smart Connections is only useful if you are already invested in its ecosystem.

Option A — Community plugin store

1. Settings → Community plugins → Browse, search "MCP Connector".
2. Install + Enable. Obsidian shows a "This plugin has not been manually reviewed by Obsidian staff" notice — community plugins pass an automated build/security review, not a hand audit.
3. The first-load migration modal opens if you have a 0.3.x install — confirm or skip the steps it proposes (see Migration from 0.3.x below).
4. Open the plugin settings and use the Quick setup for clients section to wire up your MCP client.

Option B — BRAT

Prefer the latest build, or the store entry hasn't propagated to your client yet? Install via BRAT:

1. Install and enable the Obsidian42 — BRAT plugin from the community store.
2. Settings → BRAT → Add Beta plugin, paste istefox/obsidian-mcp-connector.
3. BRAT installs the latest GitHub release; enable MCP Connector in Community plugins.
4. The first-load migration modal opens if applicable; otherwise jump straight to Quick setup for clients in the plugin settings.

That's it. No binary to install, no separate download. The MCP server starts as soon as you enable the plugin.

Advanced settings

Under the Advanced disclosure you can override the soft rate-limit warning threshold (default: 30 calls/minute). When the agent exceeds this rate, the confirmation modal surfaces a red banner so you can spot a runaway loop. The threshold is informational only — the in-process MCP server's hard limit of 100/minute is enforced server-side and is not configurable from the UI.

Where is the full reference?

This section covers the 90% case. For the complete contract (folder naming, frontmatter schema, parameter parsing rules, execution flow, known limitations), see docs/features/prompt-system.md.

Plugin runtime

• All vault access goes through Obsidian's app.vault and app.workspace APIs (Obsidian's permission model applies).
• Local REST API is no longer required for most tools — see Architecture.
• Command execution is opt-in with a per-vault allowlist; see Command execution.

Cursor / Cline / Continue / Windsurf / VS Code

Click Copy config for streamable-http clients. The snippet uses the generic streamable-http payload shape these clients accept; consult each client's own docs for the exact config-file location and any wrapping keys.

Troubleshooting

If you encounter issues: