Obsidian MCP Server: Setup Guide, Use Cases & Limitations

What Is Obsidian MCP Server?

Obsidian MCP Server connects Claude to your local Obsidian vault, enabling read and write operations on your notes directly from Claude Desktop or Claude Code. It is maintained under the Anthropic GitHub organization at the mcp-obsidian package.

Quick Facts

What You Can Do With It

• Note creation: Ask Claude to draft and write new notes directly into your vault, including frontmatter and body content.
• Knowledge base search: Query across your vault’s notes to surface relevant content by keyword or topic.
• Vault management: Organize, rename, or update existing notes without leaving your Claude session.
• Backlink analysis: Inspect which notes link to a given note, helping you map connections within your knowledge graph.

How to Set It Up

Prerequisites: Node.js must be installed. Your Obsidian vault must be accessible on the local filesystem.

Step 1 — Test the server runs:

npx mcp-obsidian
**Step 2 — Configure Claude Desktop:**

Open or create `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent path on your OS, and add the following:

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["mcp-obsidian"],
      "env": {
        "VAULT_PATH": "/absolute/path/to/your/vault"
      }
    }
  }
}

Replace /absolute/path/to/your/vault with the real path to your Obsidian vault folder.

Step 3 — Configure Claude Code (optional):

In your project directory, add or update .claude/mcp.json:

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

Restart Claude Desktop or reload your Claude Code session after saving the config.

Works Best With

This server is documented as compatible with Claude Desktop and Claude Code. Claude Desktop is the natural fit for day-to-day note management — you can maintain your knowledge base in conversational sessions without switching context. Claude Code is useful when you want vault access alongside code-related tasks, for example, writing technical documentation directly into Obsidian as part of a development workflow.

Known Limitations

• Local filesystem only: The server operates against a vault path on the local machine. Remote or synced-only vaults (e.g., vaults accessible only via Obsidian Sync cloud without a local copy) will not work unless the files are present on disk.
• No Obsidian app dependency required at runtime, but the vault must follow standard Obsidian folder structure for note parsing to behave as expected.
• File permissions: Claude (via the MCP server process) will have the same filesystem permissions as the user running npx mcp-obsidian. Ensure the vault directory is readable and writable by that user.
• No live sync awareness: If Obsidian is open and you write a note through Claude simultaneously, conflicts may arise depending on your sync setup. Close Obsidian or pause sync when doing bulk vault operations.
• Rate limits: No documented rate limits for local file access, but large vaults with thousands of notes may experience slower search responses.

Community Resources

• GitHub Repository & Issues — file bugs or check known issues directly on the repo
• Obsidian Forum — Developers & API — relevant community discussion for vault tooling and integrations
• r/ObsidianMD on Reddit — community threads on automation and Claude integrations
• Anthropic Discord — #mcp channels for general MCP server discussion and troubleshooting