/ Directory / Playground / Obsidian MCP Server
← All servers ↗ GitHub
● Community cyanheads 🔑 Needs your key

Obsidian MCP Server

by cyanheads · cyanheads/obsidian-mcp-server

Make your Obsidian vault a first-class MCP resource — eight tools for notes, tags, frontmatter, and global search via the Local REST API plugin.

cyanheads/obsidian-mcp-server bridges any MCP client (Claude Desktop, Cursor, Cline, Windsurf) to an Obsidian vault through the Obsidian Local REST API community plugin. Agents get read/write over notes, append/prepend/overwrite modes, atomic frontmatter edits, tag management, and full-vault search — all without opening Obsidian. Caches parsed metadata for fast repeated queries.

▶ Watch demo 📦 Install 💡 Use Cases

Why use it

Key features

Live Demo

What it looks like in practice

obsidian-mcp-server.replay ▶ ready
0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-mcp-server"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<from Local REST API plugin>",
        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123"
      }
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-mcp-server"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<from Local REST API plugin>",
        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123"
      }
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-mcp-server"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<from Local REST API plugin>",
        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123"
      }
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-mcp-server"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<from Local REST API plugin>",
        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123"
      }
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "obsidian-mcp-server",
      "command": "npx",
      "args": [
        "-y",
        "obsidian-mcp-server"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json
{
  "context_servers": {
    "obsidian-mcp-server": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "obsidian-mcp-server"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add obsidian-mcp-server -- npx -y obsidian-mcp-server

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Obsidian MCP Server

Capture ideas into today's daily note from any MCP client

👤 Obsidian users who live in chat ⏱ ~5 min beginner

When to use: You're mid-conversation with Claude and want a thought saved to your vault without switching apps.

Prerequisites
  • Obsidian with Local REST API plugin enabled — Community Plugins → install 'Local REST API' → copy the API key
  • MCP client configured with OBSIDIAN_API_KEY + OBSIDIAN_BASE_URL — See config block; base URL is usually http://127.0.0.1:27123
Flow
  1. Check the daily note exists
    List notes under Daily/2026-04-17.md.✓ Copied
    → File path confirmed or 'not found'
  2. Append the capture
    Append '- Idea: try X for the caching bug' to Daily/2026-04-17.md.✓ Copied
    → Append confirmed without overwriting prior entries

Outcome: A running journal that agents can add to, never clobber.

Pitfalls
  • Using overwrite mode when you meant append — Always default to append or prepend on daily notes; save overwrite for fresh drafts
Combine with: filesystem

Turn a week of notes into a review document

👤 Knowledge workers doing weekly reviews ⏱ ~20 min intermediate

When to use: You need a Friday synthesis across the week's scattered notes.

Prerequisites
  • Tagged or dated notes — Use #weekly or a Daily/ folder
Flow
  1. Search the week's notes
    Global search: notes modified this week under Daily/.✓ Copied
    → List of 5–7 file paths
  2. Read each
    Read each daily note and summarize by theme.✓ Copied
    → Themed bullets, not raw concatenation
  3. Write the review
    Write the summary to Reviews/2026-W16.md; add frontmatter status: review, tags: [weekly].✓ Copied
    → New file with proper frontmatter

Outcome: A weekly-review note built from the raw material without manual copy-paste.

Combine with: github

Consolidate messy tags across a vault

👤 Vaults that grew organically and now have #Work / #work / #WORK variants ⏱ ~30 min intermediate

When to use: Tag list is too long because of duplicates and near-duplicates.

Flow
  1. List current tags
    Use obsidian_manage_tags to list all tags sorted by usage.✓ Copied
    → Tag counts surface the duplicates
  2. Propose a mapping
    Propose a canonical set and a mapping from old → new.✓ Copied
    → Small, reviewable table
  3. Apply in batch
    After I confirm, rename tags across the vault using the mapping.✓ Copied
    → Tag operations summarized per note

Outcome: Clean tag taxonomy you can actually navigate.

Pitfalls
  • Rewriting hundreds of notes in one go with no backup — Commit the vault to git first; review the diff
Combine with: git

Drop web clippings into a research inbox and auto-tag them

👤 Researchers, analysts, anyone with a clipper habit ⏱ ~15 min beginner

When to use: Inbox/ folder piles up faster than you can process it.

Prerequisites
  • A designated Inbox/ folder — Create it in the vault
Flow
  1. List inbox
    List untagged notes under Inbox/.✓ Copied
    → Paths of pending items
  2. Classify and tag
    For each, suggest 1–3 tags based on content, then apply with obsidian_manage_tags.✓ Copied
    → Tags added atomically via frontmatter

Outcome: Inbox stays small; new clips get organized automatically.

Combine with: fetch

Combinations

Pair with other MCPs for X10 leverage

obsidian-mcp-server + fetch

Clip a URL with fetch, then write it into Inbox/

Fetch https://... and save a cleaned summary to Inbox/YYYY-MM-DD-title.md with proper frontmatter.✓ Copied
obsidian-mcp-server + github

Copy merged PR summaries into Projects/<repo>.md

Look up merged PRs this week and append a summary under ## Week 16 in Projects/acme-api.md.✓ Copied
obsidian-mcp-server + git

Version your vault and commit batch changes

After tag cleanup, run git diff on the vault and summarize before committing.✓ Copied

Tools

What this MCP exposes

ToolInputsWhen to callCost
obsidian_read_note path: str Read a specific note before editing or summarizing it 0
obsidian_update_note path: str, content: str, mode: 'append'|'prepend'|'overwrite' Add or replace note content — default to append unless rewriting 0
obsidian_search_replace path: str, find: str, replace: str Targeted in-note edits without regenerating the whole file 0
obsidian_global_search query: str, filters? Find notes across the whole vault 0
obsidian_list_notes folder?: str Enumerate notes in a folder before batch ops 0
obsidian_manage_frontmatter path: str, op: 'get'|'set'|'delete', key?: str, value?: any Atomic, key-level frontmatter changes 0
obsidian_manage_tags path?: str, op: 'list'|'add'|'remove' Tag hygiene and taxonomy operations 0
obsidian_delete_note path: str Remove a note — permanent, no undo 0

Cost & Limits

What this costs to run

API quota
No external API — Local REST API runs on your Mac/PC
Tokens per call
Note-sized; typical 200–3000
Monetary
Free
Tip
Prefer global_search + read on demand instead of bulk-listing entire folders into context.

Security

Permissions, secrets, blast radius

Credential storage: OBSIDIAN_API_KEY in env var only — never committed. Treat it like a local admin token to your vault.
Data egress: All traffic is localhost → Obsidian Local REST API. No cloud calls from this server.

Troubleshooting

Common errors and fixes

ECONNREFUSED 127.0.0.1:27123

Obsidian isn't running or the Local REST API plugin is disabled. Open Obsidian and enable the plugin.

Verify: curl -H 'Authorization: Bearer $OBSIDIAN_API_KEY' http://127.0.0.1:27123/vault/
401 Unauthorized

OBSIDIAN_API_KEY does not match the plugin's current key. Copy the value from the plugin settings again.

Verify: Plugin Settings → Local REST API → copy the API key
404 on a known file

Path is vault-relative and case-sensitive — confirm with obsidian_list_notes.

Verify: obsidian_list_notes folder='Daily'

Alternatives

Obsidian MCP Server vs others

AlternativeWhen to use it insteadTradeoff
obsidian-plugin-skillYou want Claude to help author Obsidian plugins, not edit vault contentDifferent scope
filesystem MCPYou're fine with raw file ops and don't need Obsidian-aware frontmatter/tag APIsYou lose atomic tag/frontmatter operations

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills