1. Home
  2. iMCP
  3. iMCP for Windsurf: Setup & Config

Data as of

iMCP for Windsurf: Setup & Config

Windsurf: Connect an MCP assistant to selected macOS personal-data services through a menu-bar app. iMCP exposes calendar, contacts, messages, reminders, location, maps, and weather capabilities with explicit system permissions.

What you can do with iMCP in Windsurf

Choose it for permission-controlled access to macOS personal services through an MCP assistant.

  • Find a contact using a name, email address, or phone number.
  • Combine current location with weather or route questions.

Before you start: iMCP in Windsurf

  • macOS 15.3 or later
  • iMCP app installed and open
  • Permissions granted for the chosen services
  • An MCP-compatible client

The executable path appears in the README's Claude Code and Amp commands. Install the app from its download page or with brew install --cask mattt/tap/iMCP. Activate services in the app and approve the connecting client.

iMCP Windsurf configuration

  1. Choose Windsurf configuration scope

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

  2. Add iMCP to Windsurf

    Use the iMCP entry below in mcpServers. Keep iMCP's documented stdio connection fields and your other Windsurf entries.

  3. Check iMCP in Windsurf

    iMCP: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json

Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

JSON
{
  "mcpServers": {
    "iMCP": {
      "command": "/Applications/iMCP.app/Contents/MacOS/imcp-server",
      "args": [],
      "env": {}
    }
  }
}

iMCP tools available to Windsurf

iMCP's stored tool list documents 1 tool; compare it with Windsurf's connected tool list, because the stored list is not a live check.

fetchContacts

After refreshing iMCP in Windsurf settings, check Cascade's tool list for fetchContacts.

Retrieve contact records through Apple's Contacts framework as JSON-LD.

iMCP: full stored tool descriptions

Troubleshooting iMCP in Windsurf

  • Check imcp-server on the machine running Windsurf's MCP integration for iMCP; refresh MCP and inspect Cascade's tools.
  • iMCP uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
  • Known limitation: Requires macOS 15.3 or newer.
  • Known limitation: Connected AI clients may send retrieved personal data off device.
  • Known limitation: Message access needs explicit selection of the local message database.
  • General Windsurf troubleshooting lives in the /clients/windsurf guide.

iMCP — details. Windsurf guide

Frequently asked questions

Windsurf reads iMCP under mcpServers in ~/.codeium/windsurf/mcp_config.json on macOS/Linux; Windows uses %USERPROFILE%\.codeium\windsurf\mcp_config.json.

Windsurf's iMCP example uses stdio.

iMCP's Windsurf configuration invokes imcp-server.

iMCP's stored list contains 1 tool, including fetchContacts. Compare those names with Windsurf's connected tool list; the stored list is not a live check.

No. Services start inactive and are enabled individually after the relevant permission prompt.

The bundled imcp-server process uses stdio with the client and relays requests to the app through local Bonjour discovery.