Obsidian MCP

A local MCP server for the official Obsidian CLI, with explicit vault access, disabled-by-default destructive tools, and a command catalog grounded in actual CLI help. Built for Windows and Node.js; communicates over stdio.

Use it to read, search, create, and update notes; inspect links, tags, properties, and tasks; and access additional Obsidian features through opt-in tools. It is an independent community project, not an official Obsidian integration.

Status: initial implementation, tested against Obsidian 1.15.0. See the verification report for what was actually exercised and what remains blocked. Command coverage is not a claim of complete live testing.

Start here

1. Install Node.js 24 or later and Obsidian with its official CLI.

2. Enable Settings → General → Command line interface in Obsidian.

3. Open a disposable vault named mcp-test for your first run.

4. Clone and build:

git clone https://github.com/GranatenUdo/obsidian-mcp.git
cd obsidian-mcp
npm ci
npm run build
npm test

5. Copy obsidian-mcp.config.example.json to obsidian-mcp.config.json and set your .com executable path if needed. The real configuration is ignored by Git.

6. Connect your MCP client using the examples below. Obsidian must be available when the server performs its startup capability check.

The repository is installed from source. No globally installed wrapper, Obsidian community plugin, HTTP server, or API key is required. npm start starts an MCP process, not an interactive terminal application.

Related MCP server: Obsidian MCP Server

Connect Claude Desktop

Merge this entry into %APPDATA%\Claude\claude_desktop_config.json without replacing your other servers. Change the checkout and executable paths.

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["C:\\Projects\\obsidian-mcp\\dist\\index.js"],
      "env": {
        "OBSIDIAN_MCP_VAULTS": "mcp-test",
        "OBSIDIAN_MCP_EXECUTABLE": "C:\\Users\\YOUR_USER\\AppData\\Local\\Programs\\Obsidian\\Obsidian.com"
      }
    }
  }
}

Fully restart Claude Desktop after changing its configuration. If Desktop cannot find Node, use the absolute path to node.exe in command.

Connect Claude Code

From PowerShell, substitute your checkout and .com paths:

claude mcp add --transport stdio --scope user --env OBSIDIAN_MCP_VAULTS=mcp-test --env "OBSIDIAN_MCP_EXECUTABLE=C:\Users\YOUR_USER\AppData\Local\Programs\Obsidian\Obsidian.com" obsidian -- node "C:\Projects\obsidian-mcp\dist\index.js"
claude mcp list

These instructions configure a local stdio server. They do not expose it to claude.ai or install a cloud proxy. Anthropic documents local Desktop MCP and remote web connectors as different mechanisms; web availability is not promised. See client setup and acceptance.

Try it

Ask your client to use the following tools with these arguments:

{"tool":"obsidian_files","arguments":{"vault":"mcp-test","limit":20}}
{"tool":"obsidian_create","arguments":{"path":"MCP Demo/Hello.md","content":"# Hello\n\nGrüße aus Obsidian!\n","dryRun":true}}
{"tool":"obsidian_read","arguments":{"path":"MCP Demo/Hello.md","offset":0,"limit":1000}}
{"tool":"obsidian_search","arguments":{"query":"Grüße","limit":20}}

The tool/arguments wrapper is illustrative; an MCP client sends the named tool call. Remove dryRun to create the example note. JSON \n in the example decodes to an actual newline; literal backslash-n text is rejected because the installed CLI rewrites it.

For typed frontmatter, use obsidian_note_upsert:

{
  "path": "MCP Demo/Review.md",
  "frontmatter": { "tags": ["review", "weekly"], "reviewed": false },
  "body": "# Weekly review\n\n- [ ] Review open tasks\n",
  "overwrite": false
}

Existing notes require overwrite: true. Supplied frontmatter keys replace the same keys; unspecified keys remain. The body is replaced in full.

Safety defaults

Unrestricted commands additionally require allowUnrestrictedCommands: true. The vault allowlist is an application policy, not an operating-system sandbox. Do not enable unrestricted tools for untrusted agents. Note contents themselves are untrusted data and may contain prompt injection.

The server makes no network requests or telemetry calls of its own. Obsidian may Sync or perform network operations, and your MCP client may send returned note content to its model provider. Local transport does not mean local-only AI.

Documentation

Contributions are welcome: start with CONTRIBUTING.md. Please report security issues as described in SECURITY.md, without posting private notes or configuration. Licensed under MIT.