How to connect Obsidian to Claude Code

Checked against Claude Code's documentation on Oct 26, 2026. Commands and config blocks are generated from the same install data as each listing page.

1. 1. Check what you need

   Node.js supplies npx, which launches the server, so confirm it is present before anything else. The vault path and the OpenAI key are covered next.

   node --version

   Copy

   • It needs OBSIDIAN_VAULT_PATH and OPENAI_API_KEY (next step).

2. 2. Get OBSIDIAN_VAULT_PATH and OPENAI_API_KEY

   Gather the vault path first, since it is the required value. The OpenAI key can wait if you have no need for remote embeddings.

   • OBSIDIAN_VAULT_PATH (required): Absolute path to the Obsidian vault to index and search.
   • OPENAI_API_KEY (optional): Optional API key for OpenAI-compatible remote embeddings; omit to use local embeddings.

3. 3. Add Obsidian Hybrid Search to Claude Code

   You can register the server with a single claude mcp add command, or put the same setup in .mcp.json for the project. In the .mcp.json route the values are referenced as environment variables, which the final block sets in your shell.

   claude mcp add --transport stdio --env OBSIDIAN_VAULT_PATH=YOUR_OBSIDIAN_VAULT_PATH --env OPENAI_API_KEY=YOUR_OPENAI_API_KEY --scope user obsidian-hybrid-search -- npx -y obsidian-hybrid-search@0.17.2 mcp

   Copy

   {
     "mcpServers": {
       "obsidian-hybrid-search": {
         "command": "npx",
         "args": [
           "-y",
           "obsidian-hybrid-search@0.17.2",
           "mcp"
         ],
         "env": {
           "OBSIDIAN_VAULT_PATH": "${OBSIDIAN_VAULT_PATH}",
           "OPENAI_API_KEY": "${OPENAI_API_KEY}"
         }
       }
     }
   }

   Copy

   export OBSIDIAN_VAULT_PATH="paste-your-value-here"
   export OPENAI_API_KEY="paste-your-value-here"

   Copy

   • The command keeps the value in ~/.claude.json; the .mcp.json version refers to an environment variable, so nothing secret is committed.

4. 4. Restart or reload if it does not appear

   If Obsidian Hybrid Search is not listed after you add it, start here. This step explains when Claude Code connects servers and how it handles approval for project-level files.

   • The docs do not say a restart is needed after claude mcp add. Servers connect at startup and can be reconnected from the /mcp menu.
   • In an interactive session Claude Code asks you to approve servers from a project .mcp.json before it uses them; claude mcp reset-project-choices resets those answers.

claude mcp list