MCP Directory

How to add obsidian-mcp-server (cyanheads) to Windsurf

Surgical Obsidian vault editing — read, write, search, and patch notes, tags, and frontmatter. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 15, 2026 · 590★ · stdio · apikey

Windsurf config for obsidian-mcp-server (cyanheads)

npx -y obsidian-mcp-server@latest
{
  "mcpServers": {
    "obsidian-mcp-server-cyanheads": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-mcp-server@latest"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<your-obsidian-rest-api-key>",
        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
        "OBSIDIAN_VERIFY_SSL": "false"
      }
    }
  }
}

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the obsidian-mcp-server (cyanheads) config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5obsidian-mcp-server (cyanheads)'s tools become available to Cascade.

Before you start

  • Bun v1.3.11+ or Node.js v24+ (run via bunx/npx, no global install needed)
  • Obsidian desktop app with the Local REST API community plugin v4.0.0+ installed and enabled
  • An API key generated in the Local REST API plugin settings, supplied as OBSIDIAN_API_KEY
  • The plugin's base URL (defaults to http://127.0.0.1:27123); Obsidian must be running for the server to work
  • Optional: the Omnisearch plugin for BM25-ranked semantic search

What obsidian-mcp-server (cyanheads) can do in Windsurf

obsidian_get_note

Read a note's content and metadata by path

obsidian_list_notes

List notes, optionally scoped to a folder

obsidian_list_tags

Enumerate all tags used across the vault

obsidian_search_notes

Multi-mode search: text, JSONLogic, or BM25 Omnisearch

obsidian_write_note

Create or overwrite a note at a given path

obsidian_append_to_note

Append content to the end of an existing note

obsidian_patch_note

Surgically edit a note targeting a heading or block reference

obsidian_replace_in_note

Find-and-replace text within a note

Security

Needs the Obsidian Local REST API plugin's bearer token (OBSIDIAN_API_KEY) with full vault access; keep it in env vars. SSL verification is off by default (OBSIDIAN_VERIFY_SSL=false) because the plugin uses a self-signed cert, so only connect to a trusted local host.

obsidian-mcp-server (cyanheads) + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the obsidian-mcp-server (cyanheads) config there under the "mcpServers" key and restart the client.

Is obsidian-mcp-server (cyanheads) safe to use with Windsurf?

Needs the Obsidian Local REST API plugin's bearer token (OBSIDIAN_API_KEY) with full vault access; keep it in env vars. SSL verification is off by default (OBSIDIAN_VERIFY_SSL=false) because the plugin uses a self-signed cert, so only connect to a trusted local host.

Why does it need the Local REST API plugin instead of reading files directly?

The server talks to Obsidian over HTTP through that plugin, which keeps the vault index and plugins in sync and lets it use features like the command palette and Omnisearch. Obsidian must be running.

How do I authenticate?

Generate an API key in the Local REST API plugin settings and pass it as the OBSIDIAN_API_KEY environment variable. The MCP server itself can optionally add JWT/OAuth, but by default no extra auth is required for stdio.

Can I stop an agent from deleting or overwriting notes?

Yes. Set OBSIDIAN_READ_ONLY for a global write kill switch, scope writes with OBSIDIAN_WRITE_PATHS, and deletes require human-in-the-loop confirmation.

View repo Full obsidian-mcp-server (cyanheads) page