Obsidian MCP Server

<br>

An MCP (Model Context Protocol) server that lets AI agents work inside an Obsidian vault: read notes, search context, inspect links, follow vault-specific rules, and optionally create or edit notes safely.

It is designed for clients and harnesses such as Codex, Claude Code, Hermes, and Claude Desktop. The core stays reusable; each vault can layer its own profiles, rules, skills, and optional tool sets on top.

Tools are generic. Behavior comes from the vault.

flowchart LR
    Clients["Codex, Claude Code, Hermes, Claude Desktop"] --> MCP["Obsidian MCP Server"]
    MCP --> Core["Core tools: read, search, inspect, route"]
    MCP --> Optional["Optional tool sets: write, graph, canvas, ObsidianRAG"]
    Core --> Vault["Obsidian vault"]
    Optional --> Vault
    Vault --> Profile[".agents/vault.yaml, rules, skills, standards"]
    Profile --> MCP

---

Features

Public Core

The core tool set is always available and stays vault-agnostic:

• Vault diagnostics, task routing, and MCP client root inspection.
• Note listing, reading, metadata inspection, and search.
• Vault context resources for profiles, skills, standards, and local docs.
• Core prompts for structured notes, template usage, and context exploration.

Optional Tool Sets

Optional packs are enabled explicitly from .agents/vault.yaml or OBSIDIAN_MCP_TOOL_SETS:

• notes_write: Create, patch, move, and delete notes.
• vault_analysis: Vault statistics, tags, links, backlinks, and graph tools.
• agents_admin: Skill creation, validation, and cache management.
• youtube: Transcript extraction.
• obsidianrag: Semantic search through the external ObsidianRAG service.
• canvas / kanvas: Canvas and workflow helpers.
• Profile packs: Personal workflows only when a vault profile opts in.

Design Principles

• Public core, personal profiles: The repository remains reusable; local workflows live in vault configuration and resources.
• English technical surface: Tool names, prompt names, docs, and code identifiers are English.
• Safe by default: Write tools are opt-in, protected paths are blocked, and large reads are capped.
• External RAG by integration: Advanced semantic search delegates to ObsidianRAG instead of duplicating a RAG stack inside the MCP server.

Quick Start

Prerequisites

• uv
• An Obsidian vault path you are comfortable exposing to an MCP client

Beta install from Git

Until the package is published to PyPI, install directly from GitHub with uvx:

uvx --from git+https://github.com/Vasallo94/obsidian-mcp-server.git obsidian-mcp-server

For Codex, add this to ~/.codex/config.toml:

[mcp_servers.obsidian]
command = "uvx"
args = [
  "--from",
  "git+https://github.com/Vasallo94/obsidian-mcp-server.git",
  "obsidian-mcp-server",
]
startup_timeout_sec = 30
tool_timeout_sec = 120

[mcp_servers.obsidian.env]
OBSIDIAN_VAULT_PATH = "/absolute/path/to/your/vault"

For Claude Code, Hermes, Claude Desktop, and MCPB setup, see Installation.

Local development

git clone https://github.com/Vasallo94/obsidian-mcp-server.git
cd obsidian-mcp-server
make install
cp .env.example .env
# Set OBSIDIAN_VAULT_PATH to the absolute path to your Obsidian vault
uv run obsidian-mcp-server

Once the package is published to PyPI, client configs can use:

uvx obsidian-mcp-server

---

Usage

Optional Tool Sets

Enable optional tools from the client environment:

{
  "env": {
    "OBSIDIAN_VAULT_PATH": "/Absolute/Path/To/Your/Vault",
    "OBSIDIAN_MCP_TOOL_SETS": "notes_write,vault_analysis,obsidianrag"
  }
}

Or declare them in your vault profile:

profile:
  name: "my_profile"
  prompt_sets:
    - "mermaid"
  tool_sets:
    - "notes_write"
    - "vault_analysis"
  standards:
    media: "Standards/Media.md"
  local_docs:
    index: "README.md"

ObsidianRAG Integration

For semantic vault search, enable the obsidianrag tool set and declare the integration:

profile:
  tool_sets:
    - "obsidianrag"
  integrations:
    obsidianrag:
      project_path: "/path/to/ObsidianRAG"
      api_url: "http://127.0.0.1:8000"
      env:
        OBSIDIANRAG_LLM_MODEL: "gemma3"
        OBSIDIANRAG_OLLAMA_EMBEDDING_MODEL: "embeddinggemma"

Then read obsidian://integrations/obsidianrag/setup or call rag.setup_status. Agents should show setup commands before installing dependencies, starting services, pulling models, or rebuilding the index.

Technical Documentation

To dive deeper into how the server works and how to customize it, check our detailed guides located in the docs/ folder:

1. Documentation Home: Wiki-style map of the project docs.
2. Installation: Setup for Codex, Claude Code, Hermes, Claude Desktop, and MCPB.
3. Architecture: Runtime architecture, tool sets, resources, prompts, and security model.
4. Tool Reference: Complete list of public MCP tools.
5. Server Configuration: Environment variables, vault profiles, tool sets, and integrations.
6. Agent Setup: How to organize your vault (.agents/) with skills and contextual rules.
7. Semantic Search: ObsidianRAG integration and legacy RAG migration notes.
8. Agent Feedback: How agents can report MCP friction with AFP out-of-band.
9. Future Roadmap: Planned improvements and next steps for the server.

For contribution, release, and security process, see CONTRIBUTING.md, SECURITY.md, and Release Checklist.

---

Development & Quality

| Command | Description | | :--- | :--- | | make test | Run the test suite (pytest) | | make lint | Run static checks (Ruff + Pyright) | | make format | Automatically format code | | make dev | Run the MCP server locally |

---

License

This project is licensed under the MIT License.