MCP Server for Obsidian for Windsurf: Setup & Config

What you can do with MCP Server for Obsidian in Windsurf

Let assistants search existing vault knowledge and write results back into structured Obsidian notes.

• Read meeting notes and write a summary into a new note.
• List vault directories and organize note files.

Before you start: MCP Server for Obsidian in Windsurf

• Obsidian with the Local REST API community plugin installed, enabled, and running
• The plugin's API key
• uvx
• An MCP-compatible client

Use the plugin settings to obtain the API key. If the client cannot locate uvx, replace the command with its absolute executable path.

MCP Server for Obsidian Windsurf configuration

1. Choose Windsurf configuration scope

   For MCP Server for Obsidian, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add MCP Server for Obsidian to Windsurf

   Use the mcp-obsidian entry below in mcpServers. Keep MCP Server for Obsidian's documented stdio connection fields and your other Windsurf entries.

3. Check MCP Server for Obsidian in Windsurf

   MCP Server for Obsidian: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "uvx",
      "args": [
        "mcp-obsidian"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<API key from your Obsidian Local REST API plugin>",
        "OBSIDIAN_HOST": "<Obsidian API host; defaults to 127.0.0.1>",
        "OBSIDIAN_PORT": "<Obsidian API port; defaults to 27124>"
      }
    }
  }
}

MCP Server for Obsidian tools available to Windsurf

MCP Server for Obsidian's stored tool list documents 7 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

list_files_in_vault

After refreshing MCP Server for Obsidian in Windsurf settings, check Cascade's tool list for list_files_in_vault.

List files and directories at the vault root.

list_files_in_dir

After refreshing MCP Server for Obsidian in Windsurf settings, check Cascade's tool list for list_files_in_dir.

Inspect files and subdirectories within a selected vault directory.

get_file_contents

After refreshing MCP Server for Obsidian in Windsurf settings, check Cascade's tool list for get_file_contents.

search

After refreshing MCP Server for Obsidian in Windsurf settings, check Cascade's tool list for search.

Find vault documents containing a supplied text query.

patch_content

After refreshing MCP Server for Obsidian in Windsurf settings, check Cascade's tool list for patch_content.

append_content

After refreshing MCP Server for Obsidian in Windsurf settings, check Cascade's tool list for append_content.

delete_file

After refreshing MCP Server for Obsidian in Windsurf settings, check Cascade's tool list for delete_file.

Remove a file or directory from the vault.

MCP Server for Obsidian: full stored tool descriptions

Troubleshooting MCP Server for Obsidian in Windsurf

• Check uvx mcp-obsidian (from uv, for Python tools) on the machine running Windsurf's MCP integration for MCP Server for Obsidian; refresh MCP and inspect Cascade's tools.
• Check OBSIDIAN_API_KEY, OBSIDIAN_HOST, OBSIDIAN_PORT for MCP Server for Obsidian; do not bypass a Windsurf permission error with a broad administrator token.
• MCP Server for Obsidian uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires the Obsidian Local REST API community plugin to be running.
• Known limitation: Setup needs the plugin API key and correct connection details.
• Known limitation: Deletion tools can remove vault files or directories.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions