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):

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