English Français العربية

Obsidian MCP

Official registry Productivity

Turns Obsidian vaults into AI-queryable knowledge graphs with 12 tools

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @smammadov/obsidian-mcp
Claude Code 
claude mcp add obsidian-mcp -- npx -y @smammadov/obsidian-mcp@1.0.3
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "obsidian-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@smammadov/obsidian-mcp@1.0.3"
            ]
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. obsidian-mcp
  2. Quick Start
  3. Tools (12)
  4. Configuration
  5. How It Works
  6. Development
  7. License

obsidian-mcp

MCP server that turns any Obsidian vault into an AI-queryable knowledge graph.

What makes this different from the 24+ existing Obsidian MCP servers:

  • Graph-first — BFS, shortest path, connected components, bridge detection via [[wikilinks]]
  • Zero infrastructure — No database, no Obsidian running, no API keys
  • Vault-agnostic — Works with any existing vault, no required structure
  • Backlink-aware writes — move_note auto-updates all references across the vault
  • Tiny — 4 runtime dependencies, ~42KB bundle

Quick Start

npx obsidian-mcp --vault ~/my-obsidian-vault
Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp", "--vault", "/path/to/vault"]
    }
  }
}
Claude Code
claude mcp add obsidian -- npx -y obsidian-mcp --vault /path/to/vault

Tools (12)

Reading & Discovery
ToolDescription
vault_statsOverview: total notes, tags, links, orphans, components, top tags/hubs
read_noteFull content + frontmatter + links + backlinks + sections
search_notesFilter by tags, folder, frontmatter, keyword. All combinable
Graph Traversal
ToolDescription
graph_neighborsDirect links + backlinks for a note
graph_traverseBFS/DFS from a note, N hops deep with tag filtering
graph_shortest_pathShortest link chain between two notes
graph_analyzeComponents, orphans, bridges, hubs, dead links
Writing & Manipulation
ToolDescription
create_noteCreate with content + frontmatter
patch_noteAppend, prepend, or replace a section. Update frontmatter
move_noteRename/move + auto-update all backlinks across vault
delete_noteDelete + report broken links
manage_tagsAdd/remove/rename tags (vault-wide rename supported)

Configuration

Zero-config by default. Optional .obsidian-mcp.json in vault root:

{
  "ignore": ["templates/", "daily-notes/", ".trash/"],
  "watchDebounce": 100,
  "maxTraversalDepth": 10,
  "maxSearchResults": 500
}
CLI Flags
--vault <path>       Path to Obsidian vault (required)
--verbose            Enable debug logging
--log-level <level>  error | warn | info | debug (default: info)

How It Works

  1. On startup, scans all .md files and builds an in-memory graph (~1-3s for 1k notes)
  2. File watcher detects changes and updates the graph incrementally (~5ms per change)
  3. Claude queries the graph via MCP tools — no re-scanning needed
  4. Write operations update both the filesystem and the graph atomically

Hardcoded exclusions: .obsidian/, .trash/, node_modules/

Development

npm install
npm test              # Run 66 tests
npm run build         # Build to dist/
npm run dev -- --vault test/fixtures/vault  # Dev mode

License

MIT

Frequently asked questions

What is Obsidian MCP?

Turns Obsidian vaults into AI-queryable knowledge graphs with 12 tools

How do I install Obsidian MCP?

It runs on your machine. In Claude Code: claude mcp add obsidian-mcp -- npx -y @smammadov/obsidian-mcp@1.0.3. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Obsidian MCP need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is Obsidian MCP open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Obsidian MCP?

It is published by seynurmammad0v. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.