obsidian-mcp-pro

The most feature-complete MCP server for Obsidian vaults.

⭐ Please star us on GitHub, it helps us reach more users!

💙 Support this project. obsidian-mcp-pro is free and open-source. If it saves you time, consider becoming a patron for ongoing support, or tipping on Ko-fi for a one-time thanks. Patrons get release notes early, priority on bug reports, and (optionally) their name in the README.

Give AI assistants deep, structured access to your Obsidian knowledge base. Read, write, search, tag, analyze links, traverse graphs, manipulate canvases, query Bases, edit by heading or block reference, run semantic search, and pull binary attachments. All through the Model Context Protocol.

41 tools, 5 prompts, 3 resources. Every tool ships with rich descriptions, typed schemas, human-readable titles, and safety annotations (readOnlyHint, destructiveHint, idempotentHint) so your agent picks the right tool, passes the right arguments, and handles results correctly. The original 23 tools earned an average 4.40/5 score and all-A grades on Glama's quality index; the 18 newer ones follow the same authoring conventions documented in docs/TOOL_AUTHORING.md.

Contents

• Features
• Quick Start
• Usage
• Configuration
• Security
• Wikilink Resolution
• Tool Reference
• MCP Resources
• Troubleshooting
• Development
• Testing
• What's New
• Contributing
• License

Features

Read & Search

• Focus-ranked full-text search across all vault notes, with query-centered snippets (cached: re-runs only re-read changed files)
• Read individual notes whole, or as a fragment by heading path, block id, or line range
• List and filter notes by folder, date, or pattern
• Search by frontmatter fields and values
• Retrieve daily notes automatically using the vault's configured filename format
• get_recent_notes orders by mtime; get_vault_stats reports counts, words, tag coverage; resolve_alias translates a display name to a real note path

Write & Modify

• Create new notes with frontmatter and content
• Append or prepend content to existing notes
• Update frontmatter properties programmatically (merge: unlisted keys are preserved)
• Move and rename notes (rewrites every wikilink, markdown link, and canvas reference across the vault by default)
• Delete notes safely; moved to the vault's .trash folder by default, with an optional permanent flag and elicitation-based confirmation
• Surgical edits by heading: update_section, insert_at_section, list_sections, plus single-note replace_in_note (regex with match-count guard) and edit_block for paragraphs tagged with ^id

Tags

• Build and query a complete tag index (incremental: cached across runs)
• Search notes by single or multiple tags
• rename_tag rewrites both inline #tag occurrences and frontmatter tags: arrays vault-wide; hierarchical mode also rebases nested sub-tags (project/alpha follows project)

Links & Graph

• Get backlinks (what links to a note)
• Get outlinks (what a note links to)
• Find orphan notes with no inbound or outbound links
• Detect broken links pointing to non-existent notes
• Traverse graph neighbors to a configurable depth

Canvas

• Read .canvas files with full node and edge data
• Add new nodes (text, file, link, group) to canvases
• Add edges between canvas nodes
• List all canvases in the vault

Bases (Obsidian 1.10+)

• list_bases enumerates .base files
• read_base returns the parsed YAML (filters, properties, views)
• query_base runs the filter DSL against the vault and returns matching notes; supports taggedWith(), file.hasTag(), file.inFolder(), comparison operators, and and/or/not combinators. Unsupported filters warn and fail closed instead of broadening results.

Attachments

• list_attachments enumerates every non-md/canvas/base file with a per-extension count summary
• find_unused_attachments flags assets no note references via embeds or markdown links; optional reclaimable-bytes report
• get_attachment returns image / audio / blob bytes inline as MCP content blocks (5 MB default cap, 50 MB hard cap)

Semantic Search (optional, Ollama or OpenAI)

• index_vault chunks each note (heading-aware), embeds via the configured provider, persists vectors to <vault>/.obsidian/cache/, and incrementally re-embeds only changed notes
• Because indexing sends readable note chunks to the configured embedding provider, index_vault requires confirm: "send-vault-text-to-embedding-provider" on each call
• search_semantic ranks notes by cosine similarity against an embedded query
• find_similar_notes reuses an existing note's embeddings, with source-topic anchoring, to surface neighbors without a live API call
• Stored snippets are returned only while the current note content hash still matches the indexed text; stale chunks are pruned on search

MCP Resources

• obsidian://note/{path} reads any note by its vault-relative path
• obsidian://tags retrieves the full tag index as JSON
• obsidian://daily gets today's daily note content

MCP Prompts

The server exposes five starter prompts that clients (Claude Desktop, Cursor) surface in their slash-command palette:

• daily-review walks today's daily note, surfaces unchecked tasks, and proposes follow-ups
• weekly-rollup aggregates the last seven daily notes into themes / decisions / open tasks
• find-stale-notes locates untouched notes and clusters them as orphaned vs. broken-linked vs. still-linked
• extract-action-items pulls all - [ ] … lines from a note (or every note matching a tag) into a checklist
• build-moc generates a Map of Content (MOC) for a tag or folder

Operational features

• Folder-scoped permissions: OBSIDIAN_READ_PATHS / OBSIDIAN_WRITE_PATHS allowlists gate every tool at the path-resolution choke point
• In-memory mtime cache speeds repeated vault scans within a running process without persisting note bodies to disk
• Progress notifications (notifications/progress) on rename_tag, find_unused_attachments, and index_vault when the client subscribes via _meta.progressToken
• Hard bulk-write latches require confirmPath for default move_note reference rewrites, confirmTag for non-dry-run rename_tag, and confirm=true for permanent deletion; clients with elicitation support also get typed prompts

Quick Start

Using Obsidian? There's also an Obsidian plugin that runs this server inside the app with a ribbon toggle and settings UI — no config-file editing. Recommended for most users.

One-Command Install (Claude Desktop / Cursor)

npx -y obsidian-mcp-pro install

This merges an entry into your claude_desktop_config.json (or ~/.cursor/mcp.json with --client=cursor), backs up the previous file, and prints next steps. Works on macOS, Windows, and Linux.

Pin a specific vault:

npx -y obsidian-mcp-pro install --vault /path/to/your/vault

Manual Claude Desktop Config

Add this to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-pro"]
    }
  }
}

If you have multiple vaults, specify which one:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-pro"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Claude Code

claude mcp add obsidian-mcp-pro -- npx -y obsidian-mcp-pro

HTTP Transport (Remote Clients, Cursor, ChatGPT, Web)

MCP_HTTP_TOKEN=your-secret npx -y obsidian-mcp-pro --transport=http --port=3333

Endpoint: http://127.0.0.1:3333/mcp (Streamable HTTP). HTTP transport requires a bearer token:

MCP_HTTP_TOKEN=your-secret npx -y obsidian-mcp-pro --transport=http