Obsidian Mcp Connector

MCP Connector for Obsidian

[](https://github.com/istefox/obsidian-mcp-connector/releases/latest) [](https://github.com/istefox/obsidian-mcp-connector/actions) [](LICENSE)

[Features](#features) | [Adaptive tool loading](#adaptive-tool-loading) | [Installation](#installation) | [Quick setup for clients](#quick-setup-for-clients) | [Prompts](#using-prompts) | [Command execution](#command-execution) | [Troubleshooting](#troubleshooting) | [Security](#security) | [Development](#development) | [Support](#support)

MCP Connector lets AI applications like Claude Desktop, Claude Code, Cursor, Cline, Continue, Windsurf, and VS Code securely access and work with your Obsidian vault through the Model Context Protocol. [^2]

Architecture

The plugin hosts the MCP server in-process inside Obsidian and exposes Streamable HTTP on 127.0.0.1:27200. No native binary ships from this repository, so there is no platform-specific executable to download and run from GitHub Releases.

• HTTP-native MCP clients (Claude Code, Cursor, Cline, Continue, Windsurf, VS Code) connect directly to the local HTTP endpoint.
• Claude Desktop (which speaks only stdio MCP) connects through the official npx mcp-remote bridge, a two-line config the plugin generates for you. On Windows, where mcp-remote currently hangs on connect, a bundled POST-only Python bridge replaces it (see [Troubleshooting](#troubleshooting)).
• Native semantic search runs entirely on-device via Transformers.js. No cloud, no Smart Connections requirement.
• Everything runs through Obsidian's own APIs. Vault reads, writes, plain-text search, and Dataview queries all go through app.vault, app.metadataCache, and the Dataview plugin API in-process. No external HTTP service is required.

Features

> Tip: all 48 tools are active by default. You can cut the per-session token cost with [adaptive tool loading](#adaptive-tool-loading), which keeps a small core active and promotes the rest on demand.

When connected to an MCP-compatible client, this plugin enables:

• Vault access: read, write, and patch notes through typed tools (get_vault_file, create_vault_file, patch_vault_file, rename_vault_file, rename_heading, list_vault_files, create_vault_directory, delete_vault_directory, and more) with native binary content for images and audio. Missing parent directories on a create or append path are auto-created. rename_vault_file preserves link integrity across the vault via app.fileManager.renameFile; rename_heading renames a heading in place and rewrites every wikilink, markdown link, and subheading-path reference pointing at it across the vault.
• Note properties: get_note_property, set_note_property, delete_note_property, and list_property_values read and edit frontmatter fields directly, including listing every value a property takes across the whole vault.
• Semantic search: search_vault_smart over an on-device embedding index. Four providers are available on demand: native MiniLM-L6-v2 (~25 MB, default), Gemma 300M (768d, recommended for non-Latin vaults), Multilingual-E5-Base (768d), and Smart Connections (if installed). Providers download once and swap live without a restart; the vault is re-indexed in the background while the previous provider keeps serving. A startup banner suggests the best provider based on your vault's character distribution.
• Plain-text and structured search: search_vault_simple (text plus context windows) and search_vault (Dataview DQL or JsonLogic). execute_dataview_query runs Dataview DQL in-process via the plugin API and returns typed results (table, list, task, calendar). DQL needs the Dataview community plugin; the JsonLogic path needs nothing.
• Periodic notes: get_or_create_daily_note, get_or_create_periodic_note (daily, weekly, monthly, quarterly, yearly), and append_to_periodic_note. Each call auto-creates the note with your configured template if it does not exist yet. Works with both the native Daily Notes plugin and the Periodic Notes community plugin.
• Vault graph and navigation: get_vault_file_partial (frontmatter field, heading section, block range, or document outline, a context-efficient partial read), list_tags (all vault tags with usage counts), get_files_by_tag (hierarchical matching), get_recent_files (ordered by mtime), get_outgoing_links, get_backlinks, and show_file_in_obsidian (reveal a note in the Obsidian UI).
• Vault intelligence: find_broken_links (link targets that do not resolve, with source file and line number), find_orphaned_notes (notes with zero incoming resolved links), search_and_replace (regex find-and-replace across the vault or scoped paths, dry_run:"true" by default for a safe preview), get_note_outline (heading TOC with level, text, line number, and anchor slug), and list_bookmarks (the full native Obsidian bookmark hierarchy: files, folders, searches, headings, blocks, groups).
• Canvas: get_canvas reads a .canvas file as structured nodes and edges, capping long text-node content with a textTruncated flag to bound token cost. add_canvas_node appends a text, file, or link node with automatic placement to the right of the existing layout, creating the canvas and parent folders if the path does not exist. connect_canvas_nodes draws an edge between two nodes by id. Writes preserve every existing field, including styling, so a canvas edited in Obsidian round-trips through a tool write with clean diffs.
• Template execution: invoke Templater templates as MCP tool calls with dynamic parameters.
• Prompt library: author MCP prompts as plain markdown files in your vault's Prompts/ folder. No plugins required, the in-process renderer handles everything. See [Using prompts](#using-prompts) below.
• Command execution (opt-in): authorize the agent to run specific Obsidian commands (e.g. editor:toggle-bold, graph:open) from a per-vault allowlist. Disabled by default; every invocation is audited. See [Command execution](#command-execution) below.
• Web fetch: the fetch tool retrieves arbitrary URLs and returns Markdown via Turndown, with pagination for long pages.

Typed output on every tool. Each tool result carries a structuredContent object next to the text payload, so clients that support it (Claude Desktop, Claude Code) get a typed object without parsing a JSON string. The text stays byte-identical, so clients that read only text keep working unchanged. Every tool also declares MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so a client can skip the confirmation prompt on read-only calls and gate it on destructive ones. List and scan tools take a limit (default 200, clamped to 1000) and flag truncated: true with a full total when a large vault would otherwise return an unbounded array.

46 vault tools in total, plus two always-on meta-tools (tool_catalog, activate_tool) that power [adaptive tool loading](#adaptive-tool-loading), for 48 tools in all. Full list in the plugin's settings, Tools available section.

Adaptive tool loading

Every tool a server advertises costs context-window tokens on each session: the client downloads the full JSON schema of every active tool before the model says a word. With all 48 tools active that is roughly 10K tokens per session. Adaptive tool loading lets you cut that cost without losing access to any tool.

Profiles

Pick a profile in Settings, MCP Connector, Tool Loading:

| Profile | Active tools | Best for | |---|---|---| | All (default) | All 46 tools + both meta-tools | Maximum capability, no behavior change from earlier versions | | Core | 13 essential tools + tool_catalog | Minimum token cost, static surface that never changes mid-session | | Adaptive | Core + frequency-promoted tools + both meta-tools | Token savings that converge on your actual usage |

The Core set covers the everyday operations: server info, active-file read/write/append, vault file read/create/list, both search tools, tags, note properties, and the daily note.

The two meta-tools

• tool_catalog (always active, read-only): returns the full inventory of all tools with their status (active, inactive, promoted), call counts, and descriptions for inactive ones. The model always knows what exists and what is switched off, regardless of profile.
• activate_tool (Adaptive and All profiles only): promotes an inactive tool by name. The tool becomes available immediately, no reconnect needed. By default the promotion lasts until the plugin reloads; pass persist: true to write it to the plugin data so it survives reloads. Every promotion shows an Obsidian notice (MCP Connector: "" promoted to active) so you always see when the model expands its own tool surface. In the Core profile this meta-tool is not exposed: Core means a fixed surface, and the model cannot grow it.

Frequency promotion

In Adaptive mode the plugin counts tool calls. When a non-core tool reaches 3 calls, it is promoted automatically and stays active on subsequent connects. The Tool Loading settings section lists the currently promoted tools, lets you remove any of them, and has a Reset button that clears counters and promotions while keeping your profile choice.

Typical flow in Adaptive mode

1. The model needs a tool that is not active (say find_broken_links).
2. It calls tool_catalog, sees the tool exists but is inactive.
3. It calls activate_tool with {"name": "find_broken_links"}, the tool is usable immediately and you see a notice in Obsidian.
4. If you use that tool often, frequency promotion makes it permanent without anyone asking.

Prerequisites

Required

• Obsidian v1.7.2 or higher.
• An MCP-compatible client. Examples: Claude Desktop, Claude Code, Cursor, Cline, Continue, Windsurf, VS Code.
• For Claude Desktop only: Node.js (any LTS version), required to run the npx mcp-remote bridge. The plugin auto-detects your Node install (including Homebrew on macOS) and offers a one-click install if it is missing.

Optional

• Templater: needed only for the execute_template tool. The prompt library works without it.
• Dataview: needed only for DQL queries through search_vault and execute_dataview_query. The JsonLogic path in search_vault works without it.
• Smart Connections: an 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.

Installation

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

Option A, Community plugin store

1. Settings, Community plugins, Browse, search "MCP Connector".
2. Install and enable. Obsidian shows a "This plugin has not been manually reviewed by Obsidian staff" notice; community plugins pass an automated build and security review, not a hand audit.
3. 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 has not 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. Jump 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.

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.

Claude Desktop

Claude Desktop only speaks stdio MCP, so it reaches the in-process server through the official mcp-remote bridge (Anthropic-maintained, no third-party code in the auth path). Node.js must be on your PATH. The plugin auto-detects it and offers a one-click Homebrew install if it is missing.

Recommended: download the .mcpb extension

1. In the plugin settings, under Quick setup for clients, click Download .mcpb.
2. Drag the file onto Claude Desktop.
3. The extension installs with no prompt and shows a blue connector icon in Settings → Extensions.

The bundle embeds your current bearer token and port directly, so no copy-paste step is required. Do not share the file. Node.js must be on your PATH (the plugin settings show a warning if it is missing).

If you rotate your token or change the server port, download a fresh .mcpb and drag it onto Claude Desktop to replace the existing extension.

Alternative: manual JSON config

For advanced users or when the .mcpb flow is not available:

1. Click Claude Desktop under Copy config snippets. The snippet looks like:

``json { "mcpServers": { "obsidian-mcp-connector": { "command": "npx", "args": [ "-y", "mcp-remote", "http://127.0.0.1:27200/mcp", "--header", "Authorization: Bearer YOUR_TOKEN" ] } } } ``

1. Paste it into your claude_desktop_config.json (Claude Desktop, Settings, Developer, Edit Config).
2. Restart Claude Desktop.

Or tick Auto-write Claude Desktop config in the plugin settings. The plugin keeps the file in sync on token rotation, with a .backup written before each rewrite.

Windows note: use the POST-only bridge

On Windows, mcp-remote has a bug that makes Claude Desktop hang for 60 seconds on connect, then fail with "Could not attach to MCP server". This is not a plugin bug: the same hang shows up against unrelated MCP servers, and Claude Code over direct HTTP is fine. Until mcp-remote ships a fix (geelen/mcp-remote#296), Windows users should skip mcp-remote and run the bundled bridge instead.

scripts/obsidian_mcp_bridge.py is a small Python script, standard library only with nothing to install, that talks to the plugin over POST requests, so it never opens the stream that triggers the hang. Point claude_desktop_config.json at it:

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["C:\\Users\\you\\obsidian_mcp_bridge.py", "http://127.0.0.1:27200/mcp"],
      "env": { "OBSIDIAN_BEARER_TOKEN": "paste-your-token-here" }
    }
  }
}

Full setup, including how to grab the script and verify it works, is in [docs/windows-post-only-bridge.md](docs/windows-post-only-bridge.md). macOS and Linux are not affected; use the standard mcp-remote config above.

Claude Code

Claude Code speaks HTTP transport natively. Click Copy config for Claude Code and paste into ~/.claude.json (project scope) or ~/.claude/settings.json (global scope):

{
  "mcpServers": {
    "obsidian-mcp-connector": {
      "type": "http",
      "url": "http://127.0.0.1:27200/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Or use claude mcp add from the CLI with the same fields.

Cursor / Cline / Continue / Windsurf / VS Code

Click Copy config for streamable-http clients. The snippet uses the generic streamable-http payload shap

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: istefox
• Source: istefox/obsidian-mcp-connector
• License: MIT

Install and usage instructions live in the source repository linked above.