obsidian-mcp-server

# Obsidian MCP Server A Model Context Protocol (MCP) server for Obsidian vault operations. Works with any MCP-compatible client including Claude Desktop, Cursor, Windsurf, and VS Code. ## Features - **Full Vault Access**: Read, write, search, and delete notes - **Link Navigation**: Get outgoing links and backlinks for any note - **Tag Management**: List all tags, find notes by tag - **Flexible Search**: Search by content, title, tags, or folder - **Two Transports**: Stdio (local) or Streamable HTTP (remote) - **Modern MCP**: Built with MCP SDK 1.6.1, Zod validation, tool annotations ## Quick Start ```bash # Install dependencies npm install # Build npm run build # Run (stdio mode) OBSIDIAN_VAULT_PATH=/path/to/vault npm start # Run (HTTP mode) OBSIDIAN_VAULT_PATH=/path/to/vault npm run start:http ``` ## Configuration ### Environment Variables | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `OBSIDIAN_VAULT_PATH` | Yes | - | Absolute path to your Obsidian vault | | `TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` | | `PORT` | No | `3000` | HTTP server port | | `HOST` | No | `127.0.0.1` | HTTP server host | | `DEBUG` | No | `false` | Enable debug logging | ### MCP Client Configuration #### Claude Desktop / Cursor / Windsurf (stdio) ```json { "mcpServers": { "obsidian": { "command": "node", "args": ["/path/to/obsidian-mcp-server/dist/index.js"], "env": { "OBSIDIAN_VAULT_PATH": "/path/to/your/vault" } } } } ``` #### HTTP Mode Start the server: ```bash OBSIDIAN_VAULT_PATH=/path/to/vault TRANSPORT=http npm start ``` Connect via `http://localhost:3000/mcp` ## Available Tools ### Note Operations | Tool | Description | |------|-------------| | `obsidian_list_notes` | List notes with pagination and folder filtering | | `obsidian_read_note` | Read a note's full content and metadata | | `obsidian_write_note` | Create or update a note | | `obsidian_delete_note` | Permanently delete a note | | `obsidian_search_notes` | Search notes by content, tags, or folder | ### Vault Information | Tool | Description | |------|-------------| | `obsidian_vault_stats` | Get vault statistics (note count, size, etc.) | | `obsidian_list_tags` | List all tags with usage counts | | `obsidian_get_tagged_notes` | Get all notes with a specific tag | ### Link Navigation | Tool | Description | |------|-------------| | `obsidian_get_links` | Get outgoing links from a note | | `obsidian_get_backlinks` | Get backlinks to a note | ## Response Formats All tools support a `response_format` parameter: - `json` (default): Structured JSON data - `markdown`: Human-readable markdown ## Development ```bash # Development mode (with auto-reload) npm run dev # Build npm run build # Test (builds and runs --help) npm test ``` ## Project Structure ``` src/ index.ts # Entry point, transport handling server.ts # MCP server with tool registrations vault.ts # Vault operations (CRUD, search, links) schemas.ts # Zod input validation schemas types.ts # TypeScript type definitions ``` ## License MIT