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. - CRUD Operations: Create, read, update, and delete notes (with safety confirmation) - Write Modes: Overwrite, append, or prepend content - Batch Reading: Read multiple notes i
Add this skill
npx mdskills install smith-and-web/obsidian-mcp-serverComprehensive MCP server with extensive vault operations, excellent docs, and flexible deployment options
1# Obsidian MCP Server23[](https://github.com/smith-and-web/obsidian-mcp-server/actions/workflows/ci.yml)4[](https://www.npmjs.com/package/@smith-and-web/obsidian-mcp-server)5[](https://ghcr.io/smith-and-web/obsidian-mcp-server)6[](LICENSE)7[](https://nodejs.org)8[](https://modelcontextprotocol.io)9[](https://www.typescriptlang.org/)10[](https://github.com/sponsors/smith-and-web)1112A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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.1314## Features1516### Note Management17- **CRUD Operations**: Create, read, update, and delete notes (with safety confirmation)18- **Write Modes**: Overwrite, append, or prepend content19- **Batch Reading**: Read multiple notes in a single request20- **File Info**: Get metadata without reading content (efficient for large vaults)21- **Move/Duplicate**: Reorganize your vault structure22- **Section Operations**: Read, append, or replace specific sections by heading2324### Frontmatter & Tags25- **Frontmatter Parsing**: Get/set YAML frontmatter as structured JSON (powered by gray-matter)26- **Tag Management**: Add/remove tags (frontmatter or inline)27- **Tag Auditing**: Find notes missing required tags28- **Tag Search**: List all tags with usage counts2930### Search & Links31- **Full-Text Search**: Search content and filenames with context32- **Backlinks**: Find all notes linking to a specific note33- **Broken Links**: Detect wiki-links that don't resolve34- **Find & Replace**: Bulk text replacement with regex support3536### Directory Operations37- **Create/Delete/Rename**: Full directory management38- **List Contents**: Browse vault structure3940### Performance41- **Token Optimization**: Optional compact response mode (40-60% smaller responses)42- **Efficient Scanning**: Get file info without reading content43- **SSE Transport**: Remote access without local installation4445## Quick Start4647### npx (Quickest)4849Run directly without installation:5051```bash52VAULT_PATH=/path/to/your/vault npx @smith-and-web/obsidian-mcp-server53```5455With options:5657```bash58VAULT_PATH=/path/to/vault PORT=3001 COMPACT_RESPONSES=true npx @smith-and-web/obsidian-mcp-server59```6061### Docker (Recommended for Production)6263**Using the pre-built image from GitHub Container Registry:**6465```bash66docker run -d \67 --name obsidian-mcp \68 -v /path/to/your/vault:/vault:rw \69 -p 3001:3000 \70 -e VAULT_PATH=/vault \71 ghcr.io/smith-and-web/obsidian-mcp-server:latest72```7374**Or with Docker Compose:**75761. **Create a `docker-compose.yml`:**77 ```yaml78 version: '3.8'79 services:80 obsidian-mcp:81 image: ghcr.io/smith-and-web/obsidian-mcp-server:latest82 container_name: obsidian-mcp83 restart: unless-stopped84 volumes:85 - /path/to/your/vault:/vault:rw86 ports:87 - "3001:3000"88 environment:89 - VAULT_PATH=/vault90 ```91922. **Start the server**93 ```bash94 docker-compose up -d95 ```96973. **Verify it's running**98 ```bash99 curl http://localhost:3001/health100 ```101102### Local Development1031041. **Install dependencies**105 ```bash106 npm install107 ```1081092. **Set environment variables**110 ```bash111 export VAULT_PATH=/path/to/your/vault112 export PORT=3000113 ```1141153. **Start the server**116 ```bash117 npm start118 # Or with auto-reload:119 npm run dev120 ```121122## AI Assistant Configuration123124### Claude Desktop125126Add to your Claude Desktop config file:127128- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`129- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`130131**Option 1: Local server (via mcp-remote)**132```json133{134 "mcpServers": {135 "obsidian": {136 "command": "npx",137 "args": ["-y", "mcp-remote", "http://localhost:3001/sse"]138 }139 }140}141```142143**Option 2: Remote server with HTTPS**144```json145{146 "mcpServers": {147 "obsidian": {148 "command": "npx",149 "args": ["-y", "mcp-remote", "https://your-domain.com/sse"]150 }151 }152}153```154155**Option 3: Direct npx (runs server locally)**156```json157{158 "mcpServers": {159 "obsidian": {160 "command": "npx",161 "args": ["@smith-and-web/obsidian-mcp-server"],162 "env": {163 "VAULT_PATH": "/path/to/your/vault",164 "PORT": "3001"165 }166 }167 }168}169```170171### Cursor172173Add to your Cursor MCP settings (Settings → MCP):174175**Option 1: Connect to running server**176```json177{178 "mcpServers": {179 "obsidian": {180 "command": "npx",181 "args": ["-y", "mcp-remote", "http://localhost:3001/sse"]182 }183 }184}185```186187**Option 2: Run server directly**188```json189{190 "mcpServers": {191 "obsidian": {192 "command": "npx",193 "args": ["@smith-and-web/obsidian-mcp-server"],194 "env": {195 "VAULT_PATH": "/path/to/your/vault",196 "PORT": "3001"197 }198 }199 }200}201```202203### Other MCP Clients204205Any MCP-compatible client can connect using `mcp-remote`:206207```bash208npx mcp-remote http://localhost:3001/sse209```210211Or connect directly to the SSE endpoint at `http://localhost:3001/sse`.212213## Available Tools214215### Note Operations216| Tool | Description |217|------|-------------|218| `read-note` | Read note contents (supports `frontmatterOnly` for efficiency) |219| `read-multiple-notes` | Batch read multiple notes |220| `create-note` | Create a new note |221| `edit-note` | Replace note contents |222| `write-note` | Write with modes: overwrite, append, or prepend |223| `delete-note` | Delete a note (requires confirmation) |224| `move-note` | Move/rename a note |225| `duplicate-note` | Copy a note to a new location |226| `get-notes-info` | Get file metadata without reading content |227228### Directory Operations229| Tool | Description |230|------|-------------|231| `list-vault` | List files and directories |232| `create-directory` | Create a new directory |233| `delete-directory` | Delete a directory (with recursive option) |234| `rename-directory` | Rename/move a directory |235236### Frontmatter & Tags237| Tool | Description |238|------|-------------|239| `get-frontmatter` | Get YAML frontmatter as JSON |240| `update-frontmatter` | Update frontmatter fields |241| `add-tags` | Add tags to frontmatter or inline |242| `remove-tags` | Remove tags from note |243| `list-tags` | List all tags with counts |244| `find-notes-by-tag` | Find notes with a specific tag |245| `search-missing-tag` | Find notes missing a tag |246| `audit-tags` | Audit folder for required tags |247248### Search & Links249| Tool | Description |250|------|-------------|251| `search-vault` | Full-text search with context |252| `get-backlinks` | Find notes linking to a note |253| `find-broken-links` | Find unresolved wiki-links |254| `find-replace` | Bulk find and replace |255256### Section Operations257| Tool | Description |258|------|-------------|259| `read-section` | Read content under a heading |260| `append-to-section` | Append to a section |261| `replace-section` | Replace section content |262| `append-to-file` | Append to end of file |263| `insert-at-marker` | Insert at a text marker |264| `list-headings` | List all headings in a note |265266## Architecture267268```269┌─────────────────┐ HTTPS/SSE ┌──────────────────┐270│ Claude Desktop │ ◄────────────────► │ MCP Server │271└─────────────────┘ │ (Express.js) │272 └────────┬─────────┘273 │274 ┌────────▼─────────┐275 │ VaultManager │276 │ (File System) │277 └────────┬─────────┘278 │279 ┌────────▼─────────┐280 │ Obsidian Vault │281 │ (Markdown) │282 └──────────────────┘283```284285## Project Structure286287```288obsidian-mcp-server/289├── src/290│ ├── index.ts # Express server entry point291│ ├── vault/292│ │ ├── VaultManager.ts # Core vault operations293│ │ └── frontmatter.ts # YAML parsing utilities294│ ├── tools/295│ │ ├── definitions.ts # MCP tool schemas296│ │ ├── handlers.ts # Tool execution logic297│ │ └── index.ts # Tool exports298│ ├── server/299│ │ ├── mcp.ts # MCP protocol handlers300│ │ └── middleware.ts # Express middleware301│ └── types/302│ └── index.ts # TypeScript type definitions303├── tests/ # Vitest unit tests304├── Dockerfile305├── docker-compose.yml306├── package.json307└── README.md308```309310## Environment Variables311312| Variable | Default | Description |313|----------|---------|-------------|314| `PORT` | `3000` | Server port |315| `VAULT_PATH` | `/vault` | Path to Obsidian vault |316| `COMPACT_RESPONSES` | `false` | Enable minified response keys for 40-60% smaller responses |317| `API_KEY` | *(none)* | API key for authentication. When set, requires Bearer token or query param |318319## API Endpoints320321| Endpoint | Method | Description |322|----------|--------|-------------|323| `/health` | GET | Health check |324| `/sse` | GET | SSE endpoint for MCP |325| `/sse` | POST | Direct MCP protocol calls |326| `/message` | POST | SSE transport messages |327328## Authentication329330The server supports optional API key authentication. When `API_KEY` is set, all `/sse` and `/message` endpoints require authentication. The `/health` endpoint remains public.331332### Enabling Authentication333334Set the `API_KEY` environment variable:335336```bash337# Docker338docker run -d \339 --name obsidian-mcp \340 -v /path/to/vault:/vault:rw \341 -p 3001:3000 \342 -e VAULT_PATH=/vault \343 -e API_KEY=your-secret-key \344 ghcr.io/smith-and-web/obsidian-mcp-server:latest345346# npx347API_KEY=your-secret-key VAULT_PATH=/path/to/vault npx @smith-and-web/obsidian-mcp-server348```349350### Authentication Methods351352Clients can authenticate using either method:3533541. **Authorization Header** (recommended):355 ```356 Authorization: Bearer your-secret-key357 ```3583592. **Query Parameter**:360 ```361 /sse?api_key=your-secret-key362 ```363364### Client Configuration with API Key365366**Claude Desktop / Cursor (via mcp-remote):**367```json368{369 "mcpServers": {370 "obsidian": {371 "command": "npx",372 "args": [373 "-y", "mcp-remote",374 "https://your-domain.com/sse?api_key=your-secret-key"375 ]376 }377 }378}379```380381**Direct npx with API key:**382```json383{384 "mcpServers": {385 "obsidian": {386 "command": "npx",387 "args": ["@smith-and-web/obsidian-mcp-server"],388 "env": {389 "VAULT_PATH": "/path/to/your/vault",390 "API_KEY": "your-secret-key"391 }392 }393 }394}395```396397### Security Considerations398399- **Generate strong keys**: Use a random string of at least 32 characters400- **HTTPS required**: Always use HTTPS when exposing the server remotely to prevent key interception401- **File Access**: The server has full read/write access to the mounted vault402- **CORS**: Currently allows all origins. Restrict in production if needed403- **Network security**: Consider additional layers like VPN or firewall rules for sensitive vaults404405## Deployment with NGINX Proxy Manager406407For remote access with SSL:4084091. Add a Proxy Host:410 - Domain: `obsidian.yourdomain.com`411 - Forward Hostname: `obsidian-mcp` (container name)412 - Forward Port: `3000`413 - Enable Websockets4144152. SSL Tab: Request Let's Encrypt certificate4164173. Advanced Tab (for SSE):418 ```nginx419 proxy_buffering off;420 proxy_cache off;421 proxy_set_header Connection '';422 proxy_http_version 1.1;423 chunked_transfer_encoding off;424 ```425426## Troubleshooting427428### Container Issues429```bash430# View logs431docker-compose logs -f obsidian-mcp432433# Restart434docker-compose restart435436# Rebuild437docker-compose up -d --build438```439440### Vault Access441```bash442# Check host mount443ls -la /path/to/your/vault444445# Check container access446docker exec obsidian-mcp ls -la /vault447```448449### SSE Connection450- Ensure websockets are enabled in your reverse proxy451- Check SSL certificate validity452- Verify firewall allows the port453454## Development455456### Quick Start457458```bash459# Clone and install460git clone https://github.com/smith-and-web/obsidian-mcp-server.git461cd obsidian-mcp-server462make install463464# Run with example vault465make dev466467# Test connection468make test-connection469```470471### Available Commands472473Run `make help` to see all available commands:474475```476Development:477 make install Install dependencies478 make dev Run server with hot-reload479 make start Run server in production mode480 make test-connection Test server connectivity481482Docker:483 make docker-build Build Docker image484 make docker-up Start Docker container485 make docker-down Stop Docker container486 make docker-logs View container logs487 make docker-restart Restart container488 make docker-shell Open shell in container489```490491### API Testing with Bruno492493The repository includes a [Bruno](https://www.usebruno.com/) collection for testing all 31 tools.4944951. Install Bruno (free, open-source API client)4962. Open the collection from `./bruno/obsidian-mcp`4973. Select the `local` or `remote` environment4984. Run requests to test each tool499500The collection is organized by category:501- `health/` - Server health and tool listing502- `notes/` - Note CRUD operations503- `directories/` - Directory operations504- `frontmatter/` - Frontmatter operations505- `tags/` - Tag management506- `search/` - Search and find-replace507- `links/` - Backlinks and broken links508- `sections/` - Section-based operations509510### Example Vault511512An example vault is included in `./examples/test-vault/` for development and testing. It includes sample notes with tags, links, and sections to test all features.513514## Contributing515516See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.517518## License519520MIT License - see [LICENSE](LICENSE) for details.521522## Related Projects523524- [Model Context Protocol](https://modelcontextprotocol.io) - Protocol specification525- [Obsidian](https://obsidian.md) - Knowledge base application526- [Claude](https://claude.ai) - AI assistant by Anthropic527
Full transparency — inspect the skill content before installing.