Labsco
iansinnott logo

Obsidian Claude Code

★ 313

from iansinnott

An Obsidian plugin that integrates Claude Code into your vaults via an MCP server.

🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#git#maps

Obsidian Claude Code

An Obsidian plugin that implements an MCP (Model Context Protocol) server to enable Claude Code integration with Obsidian vaults.

This plugin allows Claude Code and other MCP clients (like Claude Desktop) to interact with your Obsidian vault, providing AI-powered assistance with direct access to your notes and files.

Features

  • Dual Transport MCP Server: Supports both WebSocket (for Claude Code) and HTTP/SSE (for Claude Desktop)
  • Auto-Discovery: Claude Code automatically finds and connects to your vault
  • File Operations: Read and write vault files through MCP protocol
  • Workspace Context: Provides current active file and vault structure to Claude
  • Multiple Client Support: Connect both Claude Code and Claude Desktop simultaneously
  • Configurable Ports: Avoid conflicts when running multiple vaults

Tool Architecture

This plugin implements a flexible tool system that allows different tools to be exposed to different MCP clients:

Tool Categories

  1. Shared Tools (available to both IDE and MCP clients):

    • File operations: view, str_replace, create, insert
    • Workspace operations: get_current_file, get_workspace_files
    • Obsidian API access: obsidian_api

  2. IDE-specific Tools (only available via Claude Code WebSocket):

    • getDiagnostics - System and vault diagnostics
    • openDiff - Diff view operations (stub for Obsidian)
    • close_tab - Tab management (stub for Obsidian)
    • closeAllDiffTabs - Bulk tab operations (stub for Obsidian)

  3. MCP-only Tools (only available via HTTP/SSE):

    • Currently none, but the architecture supports adding them

Adding New Tools

To add a new tool to the plugin:

For Shared Tools (available to both IDE and MCP):

  1. Add the tool definition to src/tools/general-tools.ts in the GENERAL_TOOL_DEFINITIONS array
  2. Add the implementation in the createImplementations() method of GeneralTools class
  3. The tool will automatically be available to both WebSocket and HTTP clients

For IDE-specific Tools:

  1. Add the tool definition to src/ide/ide-tools.ts in the IDE_TOOL_DEFINITIONS array
  2. Add the implementation in the createImplementations() method of IdeTools class
  3. The tool will only be available to Claude Code via WebSocket

For MCP-only Tools:

  1. Add the tool definition to src/tools/mcp-only-tools.ts in the MCP_ONLY_TOOL_DEFINITIONS array
  2. Create an implementation class similar to GeneralTools or IdeTools
  3. Update src/mcp/dual-server.ts to register the tools only to the HTTP registry

Tool Registration Flow

The plugin uses a dual registry system:

  • WebSocket Registry: Contains shared tools + IDE-specific tools
  • HTTP Registry: Contains shared tools + MCP-only tools

This separation ensures that:

  • Claude Code gets access to IDE-specific functionality
  • Standard MCP clients only see appropriate tools
  • Shared functionality is available to all clients

Development

This project uses TypeScript to provide type checking and documentation. The repo depends on the latest plugin API (obsidian.d.ts) in TypeScript Definition format, which contains TSDoc comments describing what it does.

Releasing new releases

  • Update your manifest.json with your new version number, such as 1.0.1, and the minimum Obsidian version required for your latest release.
  • Update your versions.json file with "new-plugin-version": "minimum-obsidian-version" so older versions of Obsidian can download an older version of your plugin that's compatible.
  • Create new GitHub release using your new version number as the "Tag version". Use the exact version number, don't include a prefix v. See here for an example: https://github.com/obsidianmd/obsidian-sample-plugin/releases
  • Upload the files manifest.json, main.js, styles.css as binary attachments. Note: The manifest.json file must be in two places, first the root path of your repository and also in the release.
  • Publish the release.