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

Open Obsidian
Go to Settings → General
Enable Command line interface
Follow the prompt to register the CLI
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):

| Variable | Default | Description | |---|---|---| | OBSIDIAN_PATH | obsidian | Path to the Obsidian CLI binary | | OBSIDIAN_TIMEOUT | 30 | Command timeout in seconds | | OBSIDIAN_VAULT | — | Default vault name (if not specified per-call) |

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)

| Tool | Description | |---|---| | obsidian_create | Create or overwrite a file | | obsidian_read | Read file contents | | obsidian_append | Append content to a file | | obsidian_prepend | Prepend content after frontmatter | | obsidian_delete | Delete a file | | obsidian_move | Move or rename a file | | obsidian_rename | Rename a file | | obsidian_open | Open a file in Obsidian | | obsidian_file_info | Show file info | | obsidian_files | List files in the vault | | obsidian_folder_info | Show folder info | | obsidian_folders | List folders in the vault |

Search (2)

| Tool | Description | |---|---| | obsidian_search | Search vault for text | | obsidian_search_context | Search with matching line context |

Daily Notes (5)

| Tool | Description | |---|---| | obsidian_daily | Open today's daily note | | obsidian_daily_path | Get daily note file path | | obsidian_daily_read | Read daily note contents | | obsidian_daily_append | Append content to daily note | | obsidian_daily_prepend | Prepend content to daily note |

Tasks (2)

| Tool | Description | |---|---| | obsidian_tasks | List tasks in the vault | | obsidian_task | Show or update a task |

Tags (2)

| Tool | Description | |---|---| | obsidian_tags | List tags in the vault | | obsidian_tag | Get tag info |

Properties (4)

| Tool | Description | |---|---| | obsidian_properties | List properties in the vault | | obsidian_property_set | Set a property on a file | | obsidian_property_remove | Remove a property from a file | | obsidian_property_read | Read a property value |

Links (5)

| Tool | Description | |---|---| | obsidian_backlinks | List backlinks to a file | | obsidian_links | List outgoing links from a file | | obsidian_unresolved | List unresolved links | | obsidian_orphans | List files with no incoming links | | obsidian_deadends | List files with no outgoing links |

Outline (1)

| Tool | Description | |---|---| | obsidian_outline | Show headings for a file |

Templates (1)

| Tool | Description | |---|---| | obsidian_templates | List available templates |

Bookmarks (2)

| Tool | Description | |---|---| | obsidian_bookmarks | List bookmarks | | obsidian_bookmark | Add a bookmark |

Vault (1)

| Tool | Description | |---|---| | obsidian_vault | Show vault info |

Word Count (1)

| Tool | Description | |---|---| | obsidian_wordcount | Count words and characters |

Plugins (7)

| Tool | Description | |---|---| | obsidian_plugins | List installed plugins | | obsidian_plugins_enabled | List enabled plugins | | obsidian_plugin_info | Get plugin info | | obsidian_plugin_enable | Enable a plugin | | obsidian_plugin_disable | Disable a plugin | | obsidian_plugin_install | Install a community plugin | | obsidian_plugin_reload | Reload a plugin |

Workspace (4)

| Tool | Description | |---|---| | obsidian_workspace | Show workspace tree | | obsidian_workspaces | List saved workspaces | | obsidian_workspace_save | Save current layout | | obsidian_workspace_load | Load a saved workspace |

Bases (3)

| Tool | Description | |---|---| | obsidian_bases | List .base files in the vault | | obsidian_base_create | Create a new item in a base | | obsidian_base_query | Query a base and return results |

History (2)

| Tool | Description | |---|---| | obsidian_diff | Compare file versions | | obsidian_history | List file versions |

Development

# Install dev dependencies
uv sync

# Run tests
uv run pytest tests/ -v

License

MIT

MCP Servers