Obsidian MCP Server

MCP server that gives LLM agents access to your Obsidian vault through the official Obsidian CLI. Read, create, search notes, manage tasks, tags, properties, plugins and more — all via the Model Context Protocol.

Important: This server requires the Obsidian desktop app running on your machine. The CLI is a bridge to the app's internal API — it does not work without a running Obsidian instance.

Prerequisites

1. Obsidian 1.12+

You need Obsidian version 1.12 or later (with the latest installer — 1.12.4+).

Download: https://obsidian.md/download

2. Enable CLI in Obsidian

1. Open Obsidian
2. Go to Settings → General
3. Enable Command line interface
4. Follow the prompt to register the CLI
5. Restart your terminal for PATH changes to take effect

Verify it works:

obsidian --version

Windows users: You also need the Obsidian.com terminal redirector file, available to Catalyst members on the Obsidian Discord.

3. Python 3.11+ and uv

Install uv if you don't have it:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Installation

Clone the repository and install dependencies:

git clone https://github.com/Storks/obsidian-mcp.git
cd obsidian-mcp
uv sync

Verify everything is set up:

uv run obsidian-mcp

The server communicates via stdio, so you won't see any output — it's waiting for MCP messages. Press Ctrl+C to stop.

Connecting to LLM agents

The server uses stdio transport. Every MCP client needs to know how to start the process: run uv with the project directory and the obsidian-mcp command.

Below are configuration examples for popular tools. Replace /path/to/obsidian-mcp with the actual path where you cloned the repository.

Claude Code

Add via CLI:

claude mcp add obsidian-mcp -- uv run --directory /path/to/obsidian-mcp obsidian-mcp

Or add manually to .mcp.json in your project root (or ~/.claude.json for global access):

{
  "mcpServers": {
    "obsidian-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/obsidian-mcp", "obsidian-mcp"]
    }
  }
}

Restricting available tools

The server exposes 54 tools — you may not need all of them. Claude Code lets you allow or deny specific tools via .claude/settings.json (project-level) or ~/.claude/settings.json (global). Tools follow the naming pattern mcp__obsidian-mcp__<tool_name>.

Example: read-only mode — deny any tool that can modify the vault:

{
  "permissions": {
    "deny": [
      "mcp__obsidian-mcp__obsidian_create",
      "mcp__obsidian-mcp__obsidian_append",
      "mcp__obsidian-mcp__obsidian_prepend",
      "mcp__obsidian-mcp__obsidian_delete",
      "mcp__obsidian-mcp__obsidian_move",
      "mcp__obsidian-mcp__obsidian_rename",
      "mcp__obsidian-mcp__obsidian_property_set",
      "mcp__obsidian-mcp__obsidian_property_remove",
      "mcp__obsidian-mcp__obsidian_task",
      "mcp__obsidian-mcp__obsidian_bookmark",
      "mcp__obsidian-mcp__obsidian_base_create",
      "mcp__obsidian-mcp__obsidian_plugin_enable",
      "mcp__obsidian-mcp__obsidian_plugin_disable",
      "mcp__obsidian-mcp__obsidian_plugin_install",
      "mcp__obsidian-mcp__obsidian_plugin_reload",
      "mcp__obsidian-mcp__obsidian_workspace_save",
      "mcp__obsidian-mcp__obsidian_workspace_load"
    ]
  }
}

Example: allow only specific tools — useful when you want a minimal set:

{
  "permissions": {
    "allow": [
      "mcp__obsidian-mcp__obsidian_read",
      "mcp__obsidian-mcp__obsidian_search",
      "mcp__obsidian-mcp__obsidian_search_context",
      "mcp__obsidian-mcp__obsidian_files",
      "mcp__obsidian-mcp__obsidian_tags",
      "mcp__obsidian-mcp__obsidian_outline"
    ]
  }
}

Any tool not listed in allow will require manual confirmation before each use.

OpenCode

Add to opencode.json in your project root (or ~/.config/opencode/opencode.json for global access):

{
  "mcp": {
    "obsidian-mcp": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/path/to/obsidian-mcp", "obsidian-mcp"],
      "enabled": true
    }
  }
}

Codex (OpenAI)

Add via CLI:

codex mcp add obsidian-mcp -- uv run --directory /path/to/obsidian-mcp obsidian-mcp

Or add manually to ~/.codex/config.toml:

[mcp_servers.obsidian-mcp]
command = "uv"
args = ["run", "--directory", "/path/to/obsidian-mcp", "obsidian-mcp"]

Configuration

Environment variables (all optional):

Example with environment variables in .mcp.json:

{
  "mcpServers": {
    "obsidian-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/obsidian-mcp", "obsidian-mcp"],
      "env": {
        "OBSIDIAN_VAULT": "My Notes",
        "OBSIDIAN_TIMEOUT": "60"
      }
    }
  }
}

Available tools (54)

Every tool accepts an optional vault parameter to target a specific vault.

Files (12)

Search (2)

Daily Notes (5)

Tasks (2)

Tags (2)

Properties (4)

Links (5)

Outline (1)

Templates (1)

Bookmarks (2)

Vault (1)

Word Count (1)

Plugins (7)

Workspace (4)

Bases (3)

History (2)

Development

# Install dev dependencies
uv sync

# Run tests
uv run pytest tests/ -v

License

MIT