Obsidian MD MCP Server

MCP server for Obsidian vault integration with AI assistants that support MCP (Claude Desktop, OpenCode, Cursor, Windsurf, etc).

Features

Tools

• read_note(path) - Read a note with frontmatter parsing
• write_note(path, content) - Create/edit a note
• append_note(path, content) - Append content to an existing note
• search_notes(query) - Search text across all notes
• list_notes(directory?) - List all notes in vault or specific directory
• delete_note(path) - Delete a note

Resources

• Expose vault as file system resources
• Resource template: obsidian://{path}

Quick Start (npx)

The easiest way - use npx directly:

npx obsidian-md-mcp --vault-path /path/to/your/obsidian/vault

Or with environment variable:

OBSIDIAN_VAULT_PATH=/path/to/your/obsidian/vault npx obsidian-md-mcp

Client Configuration

Choose your client:

OpenCode

File: ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "obsidian": {
      "type": "local",
      "command": ["npx", "-y", "obsidian-md-mcp", "--vault-path", "/path/to/your/obsidian/vault"],
      "enabled": true
    }
  }
}

Or with environment variable:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "obsidian": {
      "type": "local",
      "command": ["npx", "-y", "obsidian-md-mcp"],
      "enabled": true,
      "environment": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Usage in prompts:

Read my daily note. use obsidian

Or add to your AGENTS.md:

When working with notes, use the obsidian MCP tools.

Claude Desktop

File: ~/Library/Application Support/Claude/claude_desktop_config.json

MacOS / Linux:

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

Windows:

{
  "mcpServers": {
    "obsidian": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "obsidian-md-mcp", "--vault-path", "C:\\path\\to\\your\\obsidian\\vault"]
    }
  }
}

Cursor

File: ~/.cursor/mcp.json (global) or .cursor/mcp.json in project root

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

Windsurf

File: ~/.codeium/windsurf/mcp_config.json

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

Zed

File: ~/.config/zed/settings.json

{
  "mcp_servers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-md-mcp", "--vault-path", "/path/to/your/obsidian/vault"]
    }
  }
}

Goose (by Block)

File: ~/.config/goose/config.yaml

mcp_servers:
  obsidian:
    command: npx
    args:
      - -y
      - obsidian-md-mcp
      - --vault-path
      - /path/to/your/obsidian/vault

Local Development

To develop locally or use from source:

1. Clone & install:

git clone <repo-url>
cd obsidian-md-mcp
npm install
npm run build

2. Link globally:

npm link
obsidian-md-mcp --vault-path /path/to/vault

3. Or use directly in client config:

OpenCode:

{
  "mcp": {
    "obsidian": {
      "type": "local",
      "command": ["node", "/path/to/obsidian-md-mcp/dist/bin.js", "--vault-path", "/path/to/your/obsidian/vault"]
    }
  }
}

Claude Desktop / Cursor / Windsurf:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-md-mcp/dist/bin.js", "--vault-path", "/path/to/your/obsidian/vault"]
    }
  }
}

CLI Options

obsidian-md-mcp [options]

Options:
  --vault-path, -v <path>   Path to Obsidian vault (required)
  --help, -h                Show help
  --version                 Show version

Environment Variables:
  OBSIDIAN_VAULT_PATH       Alternative way to set vault path

Usage Examples

Read a note

read_note(path: "Daily Notes/2024-01-15")

Write a note with frontmatter

write_note(path: "Projects/MyProject", content: "---\ntitle: My Project\ncreated: 2024-01-15\n---\n# My Project\n\nContent here...")

Search notes

search_notes(query: "meeting")

List all notes

list_notes()
list_notes(directory: "Projects")

Append to note

append_note(path: "Daily Notes/2024-01-15", content: "\n## New Section\n\nAdded content...")