# Obsidian Mcp Connector

> Add integrations like semantic search and custom Templater prompts to Claude or any MCP client.

- **Type:** MCP server
- **Install:** `agentstack add mcp-istefox-obsidian-mcp-connector`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [istefox](https://agentstack.voostack.com/s/istefox)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [istefox](https://github.com/istefox)
- **Source:** https://github.com/istefox/obsidian-mcp-connector

## Install

```sh
agentstack add mcp-istefox-obsidian-mcp-connector
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://modelcontextprotocol.io). [^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](https://obsidian.md/) v1.7.2 or higher.
- An MCP-compatible client. Examples: [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/claude/docs/claude-code), [Cursor](https://cursor.com), [Cline](https://github.com/cline/cline), [Continue](https://continue.dev), [Windsurf](https://codeium.com/windsurf), [VS Code](https://code.visualstudio.com).
- For **Claude Desktop only**: [Node.js](https://nodejs.org) (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](https://silentvoid13.github.io/Templater/): needed only for the `execute_template` tool. The prompt library works without it.
- [Dataview](https://blacksmithgu.github.io/obsidian-dataview/): needed only for DQL queries through `search_vault` and `execute_dataview_query`. The JsonLogic path in `search_vault` works without it.
- [Smart Connections](https://smartconnections.app/): 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](https://github.com/TfTHacker/obsidian42-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`](https://www.npmjs.com/package/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"
         ]
       }
     }
   }
   ```
2. Paste it into your `claude_desktop_config.json` (Claude Desktop, Settings, Developer, Edit Config).
3. 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](https://github.com/geelen/mcp-remote/issues/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:

```json
{
  "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):

```json
{
  "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](https://github.com/istefox)
- **Source:** [istefox/obsidian-mcp-connector](https://github.com/istefox/obsidian-mcp-connector)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-istefox-obsidian-mcp-connector
- Seller: https://agentstack.voostack.com/s/istefox
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.