Obsidian Claude Code

This MCP server enables Claude Code and Claude Desktop to interact with your Obsidian vaults using a dual-transport setup. It lets you read and write vault files, access workspace context, and connect multiple clients safely across configurable ports.

How to use

Connect Claude Code via WebSocket to your Obsidian vault to gain real-time AI-assisted editing and navigation. For Claude Desktop, use the HTTP/SSE path so Claude Desktop can stream from the same vault. Your vault becomes a live data source that Claude can query to read file contents, list files, and apply edits.

How to install

Prerequisites: ensure you have Node.js installed to run MCP-related tooling. You also need Obsidian with this MCP server plugin installed and enabled.

Install and enable the MCP server plugin in Obsidian. Then start Obsidian with the vault you want to expose.

Configure the client connections from the respective MCP clients. The default HTTP transport port is 22360, and the server exposes an SSE endpoint for HTTP-based clients and a WebSocket path for Claude Code.

Use the following configuration examples to connect Claude Desktop and Claude Code to your MCP server.

Configuration examples

{
  "mcpServers": {
    "obsidian": {
      "url": "http://localhost:22360/sse",
      "env": {}
    }
  }
}

Claude Desktop setup

Claude Desktop can connect through a local bridge that forwards the HTTP endpoint to a stdio-based workflow. Use the following snippet in your Claude Desktop config to point to the SSE endpoint.

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

Claude Code CLI setup

Claude Code automatically discovers and connects to Obsidian vaults via WebSocket. Install and enable the plugin, then run Claude Code and select your vault from the IDE list to establish the connection.

Port configuration

The default port for the MCP server is 22360 to minimize conflicts with common development services. If you run multiple vaults or encounter port conflicts, you can change the port in Obsidian Settings.

Multiple vault support

You can run the MCP server for multiple Obsidian vaults. Each vault must use a unique port. The plugin detects conflicts and guides you to configure distinct ports.

Notes on MCP specification version

This server uses the legacy HTTP with SSE transport for compatibility with Claude Code and Claude Desktop. The newer Streamable HTTP protocol is not yet supported by these clients.

Troubleshooting

Claude Desktop not connecting: Verify the config path and JSON syntax, ensure Obsidian is running with the plugin enabled, check that the port isn’t blocked by a firewall, and restart Claude Desktop after changes.

Claude Code not finding vault: Verify the plugin is enabled, check for lock files in your Claude IDE config directory, and restart Obsidian if the vault doesn’t appear in the IDE list.

Port conflicts: Configure a different port in plugin settings and update client configurations to match. Common alternative ports include 22361, 22362, 8080, 9090.

Security and privacy

When enabling MCP access, only expose vaults you intend to share with AI agents. Use local connections (localhost) for personal use and restrict access through firewall rules if exposing beyond your machine.

Available tools

view

Read file contents and metadata from the vault.

str_replace

Replace text within vault files with specified patterns.

create

Create new files or folders in the vault.

insert

Insert content into existing files at a given position.

get_current_file

Retrieve the path and contents of the currently active file.

get_workspace_files

List all files and folders in the current vault workspace.

obsidian_api

Provide access to Obsidian API capabilities from MCP clients.

getDiagnostics

Return system and vault diagnostics available to Claude Code via WebSocket.

openDiff

Open a diff view for changes (prototype functionality for Obsidian).

close_tab

Close a currently opened tab in the editor (prototype).

closeAllDiffTabs

Close all open diff tabs in a batch operation (prototype).