obsidian-claude-code

This MCP server exposes Obsidian vault content to Claude AI clients via two transports: WebSocket for Claude Code and HTTP/SSE for Claude Desktop. Claude Code discovers vaults automatically and connects over WebSocket, enabling real-time code-like interactions with your notes, including file reads, edits, and workspace context. Claude Desktop connects via the legacy HTTP/SSE path (potentially bridged with mcp-remote) to support scenarios where WebSocket is not available. Use Claude Code to query and modify notes through supported shared tools (read/write files, view, replace text, insert, and workspace queries) and take advantage of IDE-specific features when connected through WebSocket (diagnostics, diff views, tab management). If you run multiple vaults, you can allocate different ports to each instance to avoid conflicts and direct clients to the correct endpoint.

To get started, install the Obsidian plugin that implements this MCP server, ensure Node.js is installed for the Claude Desktop bridge (npx is used for mcp-remote), and configure each client to point to your Obsidian MCP server. Claude Code will auto-discover vaults via the WebSocket channel, while Claude Desktop and other HTTP-capable clients will use the configured HTTP/SSE URL. After configuration, restart affected applications and test by asking Claude about your vault contents (e.g., “What files are in my Obsidian vault?”).

Prerequisites:

• Node.js (for bridging/CLI tools) and Obsidian installed on your machine
• Access to install community plugins in Obsidian

Installation steps:

1. Install Node.js from https://nodejs.org/ (verify with node -v and npm -v).
2. Open Obsidian and enable this MCP server plugin:
   • Settings > Community Plugins > Browse, search for the Obsidian Claude Code MCP plugin, and Install/Enable it.
3. Start the Obsidian Obsidian Claude Code MCP service from the plugin UI. Note the default port: 22360. If you run multiple vaults, configure unique ports per vault in the plugin settings.
4. If using Claude Desktop, ensure npx is available (comes with Node.js) and configure Claude Desktop to connect via the mcp-remote bridge as described in the plugin’s docs.
5. For Claude Code, ensure Claude Code is installed and running; it will discover vaults automatically via WebSocket.

Optional: If you need to customize the port, update the Obsidian plugin settings under the MCP Server Configuration, then update any client configurations to point to the new port (e.g., http://localhost:22361/mcp for HTTP/SSE or http://localhost:22361/ws for WebSocket-based clients).

Tips and common issues:

• Port conflicts: If you see connection errors, verify the MCP port is not blocked by a firewall and that only one vault uses a given port. The plugin will guide you to assign a different port if conflicts occur.
• Claude Code not discovering vaults: Ensure the plugin is enabled and that any service directories used by Claude Code for IDE storage are accessible. Check for .lock files in Claude IDE directories as described in the plugin docs.
• Transport differences: WebSocket is used by Claude Code; HTTP/SSE is used by Claude Desktop. Ensure your client configurations match the transport supported by each client.
• Security: If running on a network, consider restricting access to the MCP port or using a localhost-only setup to prevent unauthorized access to vault data.
• Multiple vaults: Each vault should have its own port and distinct configuration. The plugin will help you identify port conflicts and guide port reassignment.