smith-and-web/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):
With options:
Docker (Recommended for Production)
**Using the pre-built image from GitHub Container Registry:**
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:**
2. **Start the server**
3. **Verify it's running**
Local Development
1. **Install dependencies**
2. **Set environment variables**
3. **Start the server**
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)**
**Option 2: Remote server with HTTPS**
The server must already be running (see Quick Start). Claude Desktop launches mcp-remote, which bridges its stdio to the server's SSE endpoint; Claude Desktop cannot launch this server directly, because the server does not speak stdio.
Cursor
Add to your Cursor MCP settings (Settings → MCP):
Other MCP Clients
**Claude Code** supports SSE servers directly:
Any other MCP-compatible client can connect using mcp-remote:
Or connect directly to the SSE endpoint at http://localhost:3001/sse if the client supports SSE servers natively.
Available Tools
Note Operations
| Tool | Description |
|------|-------------|
| read-note | Read note contents (supports frontmatterOnly for efficiency) |