Obsidian MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with your Obsidian vault. Access your notes, create content, manage tags, and search your knowledge base through natural conversation.

Features

Note Management

• CRUD Operations: Create, read, update, and delete notes (with safety confirmation)
• Write Modes: Overwrite, append, or prepend content
• Batch Reading: Read multiple notes in a single request
• File Info: Get metadata without reading content (efficient for large vaults)
• Move/Duplicate: Reorganize your vault structure
• Section Operations: Read, append, or replace specific sections by heading

Frontmatter & Tags

• Frontmatter Parsing: Get/set YAML frontmatter as structured JSON (powered by gray-matter)
• Tag Management: Add/remove tags (frontmatter or inline)
• Tag Auditing: Find notes missing required tags
• Tag Search: List all tags with usage counts

Search & Links

• Full-Text Search: Search content and filenames with context
• Backlinks: Find all notes linking to a specific note
• Broken Links: Detect wiki-links that don't resolve
• Find & Replace: Bulk text replacement with regex support

Semantic Search (optional)

• Search by meaning: hybrid vector + full-text retrieval over heading-aware chunks, backed by Postgres + pgvector and local embeddings from Ollama
• Similar notes: nearest notes to a given note, by whole-note embedding
• Incremental indexer: a second process from the same image that polls the vault and re-embeds only what changed; works over NFS/SMB where inotify does not
• Nothing leaves your network: embeddings are computed locally; the feature is off entirely unless DATABASE_URL is set

Directory Operations

• Create/Delete/Rename: Full directory management
• List Contents: Browse vault structure

Performance

• Token Optimization: Optional compact response mode (40-60% smaller responses)
• Efficient Scanning: Get file info without reading content
• SSE Transport: Remote access without local installation

Quick Start

How clients connect: the server speaks MCP over HTTP + SSE only (there is no stdio mode). You start it (npx, Docker or from source), then point a client at http://HOST:PORT/sse. Clients that only support stdio servers connect through mcp-remote, as shown below. It listens on all network interfaces on PORT, so set an API_KEY (see Authentication) or keep it on loopback (for example -p 127.0.0.1:3001:3000 in Docker) unless you want the whole network to have read/write access to your vault.

npx (Quickest)

Requires Node.js 20.19 or newer. This starts the server in the foreground (default port 3000):

VAULT_PATH=/path/to/your/vault npx @smith-and-web/obsidian-mcp-server

With options:

VAULT_PATH=/path/to/vault PORT=3001 COMPACT_RESPONSES=true npx @smith-and-web/obsidian-mcp-server

Docker (Recommended for Production)

Using the pre-built image from GitHub Container Registry:

docker run -d \
  --name obsidian-mcp \
  -v /path/to/your/vault:/vault:rw \
  -p 127.0.0.1:3001:3000 \
  -e VAULT_PATH=/vault \
  ghcr.io/smith-and-web/obsidian-mcp-server:latest

latest follows the newest release; pin a version tag (for example :1.6.0) for production. Drop 127.0.0.1: only if you set API_KEY and want other machines to connect.

Or with Docker Compose:

1. Create a docker-compose.yml:

   services:
     obsidian-mcp:
       image: ghcr.io/smith-and-web/obsidian-mcp-server:latest
       container_name: obsidian-mcp
       restart: unless-stopped
       volumes:
         - /path/to/your/vault:/vault:rw
       ports:
         - "127.0.0.1:3001:3000"
       environment:
         - VAULT_PATH=/vault
   

2. Start the server

   docker compose up -d
   

3. Verify it's running

   curl http://localhost:3001/health
   

Local Development

1. Install dependencies

   npm install
   

2. Set environment variables

   export VAULT_PATH=/path/to/your/vault
   export PORT=3000
   

3. Start the server

   npm start
   # Or with auto-reload:
   npm run dev
   

AI Assistant Configuration

Claude Desktop

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Option 1: Local server (via mcp-remote)

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3001/sse"]
    }
  }
}

Option 2: Remote server with HTTPS

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-domain.com/sse"]
    }
  }
}

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗