XcodeBuildMCP for Windsurf: Setup & Config

What you can do with XcodeBuildMCP in Windsurf

Choose it for Xcode agent tooling available through either MCP or a unified terminal CLI.

• Build an Xcode project for a simulator from the CLI.
• Install agent guidance for MCP or direct CLI workflows.

Before you start: XcodeBuildMCP in Windsurf

• macOS 14.5 or newer
• Xcode 16.x or newer
• Node.js 18.x or newer for the npm/npx method
• Xcode code signing for device tools

The mcp subcommand starts the server. The init subcommand installs agent skills rather than starting the server. Homebrew provides an alternative installation without Node.js.

XcodeBuildMCP Windsurf configuration

1. Choose Windsurf configuration scope

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

2. Add XcodeBuildMCP to Windsurf

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

3. Check XcodeBuildMCP in Windsurf

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

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest",
        "mcp"
      ],
      "env": {}
    }
  }
}

Troubleshooting XcodeBuildMCP in Windsurf

• Check npx xcodebuildmcp@latest (Node.js/npm) on the machine running Windsurf's MCP integration for XcodeBuildMCP; refresh MCP and inspect Cascade's tools.
• XcodeBuildMCP uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires macOS 14.5 or newer and Xcode 16.x or newer.
• Known limitation: Device tools need Xcode code signing configured.
• Known limitation: Runtime error telemetry is present; opt-out details are linked separately.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions