Skip to content
Back to search

obsidian-claude-code-mcp

Connect Claude Code and other AI tools to your Obsidian notes using Model Context Protocol (MCP)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/iansinnott--obsidian-claude-code-mcp/badge.svg)](/listings/iansinnott--obsidian-claude-code-mcp)

HTML

<a href="/listings/iansinnott--obsidian-claude-code-mcp"><img src="/api/listings/iansinnott--obsidian-claude-code-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 195 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Obsidian Claude Code
  2. An Obsidian plugin that implements an MCP (Model Context Protocol) server to enable Claude Code integration with Obsidian vaults.
  3. 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.
  4. ## Features
  5. - **Dual Transport MCP Server**: Supports both WebSocket (for Claude Code) and HTTP/SSE (for Claude Desktop)
  6. - **Auto-Discovery**: Claude Code automatically finds and connects to your vault
  7. - **File Operations**: Read and write vault files through MCP protocol
  8. - **Workspace Context**: Provides current active file and vault structure to Claude
  9. - **Multiple Client Support**: Connect both Claude Code and Claude Desktop simultaneously
  10. - **Configurable Ports**: Avoid conflicts when running multiple vaults
  11. ## MCP Client Configuration
  12. This plugin serves as an MCP server that various Claude clients can connect to. Here's how to configure different clients:
  13. ### Claude Desktop (as of 2025-06-09)
  14. Claude Desktop requires a special configuration to connect to the Obsidian MCP server because it does not directly support HTTP transports. We will use `mcp-remote`, a tool that creates a local `stdio` bridge to the server's HTTP endpoint.
  15. **Configuration Steps:**
  16. 1. **Install and enable** this plugin in Obsidian.
  17. 2. **Make sure you have Node.js installed**, as `npx` (which comes with Node.js) is used to run the bridge tool.
  18. 3. **Locate your Claude Desktop config file**:
  19. - **macOS**: `$HOME/Library/Application Support/Claude/claude_desktop_config.json`
  20. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  21. 4. **Add the Obsidian MCP server** to your config using the `mcp-remote` command. `npx` will automatically download and run it for you.
  22. ```json
  23. {
  24. "mcpServers": {
  25. "obsidian": {
  26. "command": "npx",
  27. "args": ["mcp-remote", "http://localhost:22360/sse"],
  28. "env": {}
  29. }
  30. }
  31. }
  32. ```
  33. 5. **Restart Claude Desktop** after making the configuration change.
  34. 6. **Test the connection** by asking Claude about your vault: "What files are in my Obsidian vault?"
  35. ### Other MCP Clients (with direct HTTP support)
  36. If you are using an MCP client that directly supports the legacy "HTTP with SSE" transport, you can use a simpler configuration without the `mcp-remote` bridge.
  37. **Example Configuration:**
  38. ```json
  39. {
  40. "mcpServers": {
  41. "obsidian": {
  42. "url": "http://localhost:22360/sse",
  43. "env": {}
  44. }
  45. }
  46. }
  47. ```
  48. ### Claude Code CLI
  49. Claude Code automatically discovers and connects to Obsidian vaults through WebSocket.
  50. **Usage Steps:**
  51. 1. **Install and enable** this plugin in Obsidian
  52. 2. **Run Claude Code** in your terminal: `claude`
  53. 3. **Select your vault** using the `/ide` command
  54. 4. **Choose "Obsidian"** from the IDE list
  55. 5. Claude Code will automatically connect via WebSocket
  56. ### Port Configuration
  57. **Default Port**: The plugin uses port `22360` by default to avoid conflicts with common development services.
  58. **Custom Port Setup:**
  59. 1. Go to **Obsidian Settings** → **Community Plugins** → **Claude Code** → **Settings**
  60. 2. Change the **"HTTP Server Port"** in the MCP Server Configuration section
  61. 3. **Update your Claude Desktop config** to use the new port:
  62. ```json
  63. {
  64. "mcpServers": {
  65. "obsidian": {
  66. "url": "http://localhost:22360/mcp",
  67. "env": {}
  68. }
  69. }
  70. }
  71. ```
  72. NOTE: You can change the port in the settings.
  73. 4. **Restart Claude Desktop** to apply the changes
  74. **Multiple Vaults**: If you run multiple Obsidian vaults with this plugin, each vault needs a unique port. The plugin will automatically detect port conflicts and guide you to configure different ports.
  75. ### A Note on MCP Specification Version
  76. _As of 2025-06-09_
  77. > [!IMPORTANT]
  78. > This plugin intentionally uses an older MCP specification for HTTP transport. The latest ["Streamable HTTP" protocol (2025-03-26)](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) is not yet supported by most MCP clients, including Claude Code and Claude Desktop.
  79. >
  80. > To ensure compatibility, we use the legacy ["HTTP with SSE" protocol (2024-11-05)](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse). Adhering to the newest specification will lead to connection failures with current tools.
  81. ### Troubleshooting
  82. **Claude Desktop not connecting:**
  83. - Verify the config file path and JSON syntax
  84. - Ensure Obsidian is running with the plugin enabled
  85. - Check that the port (22360) isn't blocked by firewall
  86. - Restart Claude Desktop after config changes
  87. **Claude Code not finding vault:**
  88. - Verify the plugin is enabled in Obsidian
  89. - Check for `.lock` files in Claude config directory:
  90. - `$CLAUDE_CONFIG_DIR/ide/` if environment variable is set
  91. - `~/.config/claude/ide/` (default since Claude Code v1.0.30)
  92. - `~/.claude/ide/` (legacy location)
  93. - Restart Obsidian if the vault doesn't appear in `/ide` list
  94. **Port conflicts:**
  95. - Configure a different port in plugin settings
  96. - Update client configurations to match the new port
  97. - Common alternative ports: 22361, 22362, 8080, 9090
  98. ## Tool Architecture
  99. This plugin implements a flexible tool system that allows different tools to be exposed to different MCP clients:
  100. ### Tool Categories
  101. 1. **Shared Tools** (available to both IDE and MCP clients):
  102. - File operations: `view`, `str_replace`, `create`, `insert`
  103. - Workspace operations: `get_current_file`, `get_workspace_files`
  104. - Obsidian API access: `obsidian_api`
  105. 2. **IDE-specific Tools** (only available via Claude Code WebSocket):
  106. - `getDiagnostics` - System and vault diagnostics
  107. - `openDiff` - Diff view operations (stub for Obsidian)
  108. - `close_tab` - Tab management (stub for Obsidian)
  109. - `closeAllDiffTabs` - Bulk tab operations (stub for Obsidian)
  110. 3. **MCP-only Tools** (only available via HTTP/SSE):
  111. - Currently none, but the architecture supports adding them
  112. ### Adding New Tools
  113. To add a new tool to the plugin:
  114. #### For Shared Tools (available to both IDE and MCP):
  115. 1. Add the tool definition to `src/tools/general-tools.ts` in the `GENERAL_TOOL_DEFINITIONS` array
  116. 2. Add the implementation in the `createImplementations()` method of `GeneralTools` class
  117. 3. The tool will automatically be available to both WebSocket and HTTP clients
  118. #### For IDE-specific Tools:
  119. 1. Add the tool definition to `src/ide/ide-tools.ts` in the `IDE_TOOL_DEFINITIONS` array
  120. 2. Add the implementation in the `createImplementations()` method of `IdeTools` class
  121. 3. The tool will only be available to Claude Code via WebSocket
  122. #### For MCP-only Tools:
  123. 1. Add the tool definition to `src/tools/mcp-only-tools.ts` in the `MCP_ONLY_TOOL_DEFINITIONS` array
  124. 2. Create an implementation class similar to `GeneralTools` or `IdeTools`
  125. 3. Update `src/mcp/dual-server.ts` to register the tools only to the HTTP registry
  126. ### Tool Registration Flow
  127. The plugin uses a dual registry system:
  128. - **WebSocket Registry**: Contains shared tools + IDE-specific tools
  129. - **HTTP Registry**: Contains shared tools + MCP-only tools
  130. This separation ensures that:
  131. - Claude Code gets access to IDE-specific functionality
  132. - Standard MCP clients only see appropriate tools
  133. - Shared functionality is available to all clients
  134. ## Development
  135. This project uses TypeScript to provide type checking and documentation.
  136. The repo depends on the latest plugin API (obsidian.d.ts) in TypeScript Definition format, which contains TSDoc comments describing what it does.
  137. ### Releasing new releases
  138. - Update your `manifest.json` with your new version number, such as `1.0.1`, and the minimum Obsidian version required for your latest release.
  139. - 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.
  140. - 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
  141. - 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.
  142. - Publish the release.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.