obsidian-mcp

A focused Model Context Protocol server that gives local AI clients controlled filesystem access to an Obsidian vault. It runs over stdio, works without the Obsidian application or a REST plugin, and supports read-only operation.

Use it to: search notes, read Markdown, browse folders, and optionally create, update, move, or delete notes from any stdio-capable MCP client.

Why Obsidian MCP?

• Local by design: no HTTP server, API token, or Obsidian plugin.
• Vault-contained paths: resolved paths and symbolic links cannot escape the configured vault root.
• Read-only mode: one environment variable disables every write tool.
• Small surface area: ten predictable tools backed by ordinary Markdown files.
• Fast search: uses ripgrep when available, with a pure-Python fallback.

[!CAUTION] The configured MCP client can read every Markdown note in the selected vault. Start with OBSIDIAN_READ_ONLY=1, and review your model provider's data-handling policy before exposing sensitive notes.

Quick Start

Requirements: Python 3.11 or newer and uv.

The package is published to PyPI as trsdn-obsidian-mcp (the PyPI name obsidian-mcp is taken by an unrelated project). The import name and the console command stay obsidian_mcp / obsidian-mcp.

export OBSIDIAN_VAULT_PATH="/path/to/your/Obsidian vault"
export OBSIDIAN_READ_ONLY=1

# run without installing
uvx --from trsdn-obsidian-mcp obsidian-mcp

# or install it
pip install trsdn-obsidian-mcp
obsidian-mcp

The server communicates over stdio and is normally started by an MCP client, not from an interactive terminal.

Client Setup

Replace /path/to/your/Obsidian vault in the examples below.

VS Code

Add the server to .vscode/mcp.json:

{
  "servers": {
    "obsidian": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "trsdn-obsidian-mcp",
        "obsidian-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/Obsidian vault",
        "OBSIDIAN_READ_ONLY": "1"
      }
    }
  }
}

Claude Desktop

Add the server under mcpServers in Claude Desktop's configuration:

{
  "mcpServers": {
    "obsidian": {
      "command": "uvx",
      "args": [
        "--from",
        "trsdn-obsidian-mcp",
        "obsidian-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/Obsidian vault",
        "OBSIDIAN_READ_ONLY": "1"
      }
    }
  }
}

From a local checkout

git clone https://github.com/trsdn/obsidian-mcp.git
cd obsidian-mcp
uv sync --locked --no-dev
uv run obsidian-mcp

Restart the client after changing its MCP configuration.

Configuration

Read-only mode blocks write_note, append_note, move_note, and delete_note. All paths passed to tools are relative to the configured vault.

Available Tools

Security Model

Obsidian MCP trusts the local process that starts it. It does not provide authentication, user-level authorization, sandboxing, or network controls. Path validation keeps MCP tool operations inside the selected vault, but it cannot restrict another local process that already has filesystem access.

For safer operation:

1. Use only MCP clients you trust.
2. Start with OBSIDIAN_READ_ONLY=1.
3. Consider a dedicated vault for AI-assisted workflows.
4. Protect the vault with normal operating-system permissions and backups.

See SECURITY.md for the full security policy and private vulnerability reporting process.

Development

uv sync --locked --all-groups
uv run ruff check .
uv run ruff format --check .
uv run pytest --cov=obsidian_mcp --cov-fail-under=85
uv build

Tests use temporary directories and never require a real Obsidian vault. CI runs on Python 3.11, 3.12, 3.13, and 3.14.

Project

• Releases
• Changelog
• Contributing
• Code of conduct
• Security policy
• Issue tracker

Licensed under the MIT License.