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

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

npx (Quickest)

Run directly without installation:

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 3001:3000 \
  -e VAULT_PATH=/vault \
  ghcr.io/smith-and-web/obsidian-mcp-server:latest

Or with Docker Compose:

1. Create a docker-compose.yml:

   docker-compose.yml

   Copy

   version: '3.8'
   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:
         - "3001:3000"
       environment:
         - VAULT_PATH=/vault
   

2. Start the server

   bash

   Copy

   docker-compose up -d
   

3. Verify it's running

   Terminal

   Copy

   curl http://localhost:3001/health
   

Local Development

1. Install dependencies

   Terminal

   Copy

   npm install
   

2. Set environment variables

   server.ts

   Copy

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

3. Start the server

   Terminal

   Copy

   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"]
    }
  }
}

Option 3: Direct npx (runs server locally)

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["@smith-and-web/obsidian-mcp-server"],
      "env": {
        "VAULT_PATH": "/path/to/your/vault",
        "PORT": "3001"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (Settings → MCP):

Option 1: Connect to running server

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

Option 2: Run server directly

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["@smith-and-web/obsidian-mcp-server"],
      "env": {
        "VAULT_PATH": "/path/to/your/vault",
        "PORT": "3001"
      }
    }
  }
}

Other MCP Clients

Any MCP-compatible client can connect using mcp-remote:

npx mcp-remote http://localhost:3001/sse

Or connect directly to the SSE endpoint at http://localhost:3001/sse.

Available Tools

Note Operations

Directory Operations

Frontmatter & Tags

Search & Links

Section Operations

Architecture

┌─────────────────┐     HTTPS/SSE      ┌──────────────────┐
│  Claude Desktop │ ◄────────────────► │   MCP Server     │
└─────────────────┘                    │   (Express.js)   │
                                       └────────┬─────────┘
                                                │
                                       ┌────────▼─────────┐
                                       │   VaultManager   │
                                       │   (File System)  │
                                       └────────┬─────────┘
                                                │
                                       ┌────────▼─────────┐
                                       │  Obsidian Vault  │
                                       │   (Markdown)     │
                                       └──────────────────┘

Project Structure

obsidian-mcp-server/
├── src/
│   ├── index.ts              # Express server entry point
│   ├── vault/
│   │   ├── VaultManager.ts   # Core vault operations
│   │   └── frontmatter.ts    # YAML parsing utilities
│   ├── tools/
│   │   ├── definitions.ts    # MCP tool schemas
│   │   ├── handlers.ts       # Tool execution logic
│   │   └── index.ts          # Tool exports
│   ├── server/
│   │   ├── mcp.ts            # MCP protocol handlers
│   │   └── middleware.ts     # Express middleware
│   └── types/
│       └── index.ts          # TypeScript type definitions
├── tests/                    # Vitest unit tests
├── Dockerfile
├── docker-compose.yml
├── package.json
└── README.md

Environment Variables

API Endpoints

Authentication

The server supports optional API key authentication. When API_KEY is set, all /sse and /message endpoints require authentication. The /health endpoint remains public.