XcodeMCPWrapper - mcpbridge-wrapper

A Python wrapper that makes Xcode 26.3's MCP bridge compatible with Cursor and other strict MCP-spec-compliant clients.

The Problem

Xcode's mcpbridge returns tool responses in the content field but omits the required structuredContent field when a tool declares an outputSchema. According to the MCP specification, when outputSchema is declared, responses must include structuredContent.

• ✅ Claude Code and Codex CLI work (they have special handling for Apple's responses)
• ❌ Cursor strictly follows the spec and rejects non-compliant responses

The Solution

mcpbridge-wrapper intercepts responses from xcrun mcpbridge and copies the data from content into structuredContent, making Xcode's MCP tools fully compatible with all MCP clients.

┌─────────────┐    MCP Protocol    ┌──────────────────┐   MCP Protocol   ┌────────────┐    XPC    ┌─────────┐
│   Cursor    │ ◄────────────────► │ mcpbridge-wrapper│ ◄──────────────► │ mcpbridge  │ ◄───────► │  Xcode  │
│ (MCP Client)│                    │  (This Project)  │                  │  (Bridge)  │           │  (IDE)  │
└─────────────┘                    └──────────────────┘                  └────────────┘           └─────────┘

Quick Start

Prerequisites

• macOS with Xcode 26.3+
• Python 3.9+
• Xcode Tools MCP Server enabled (see below)

⚠️ Important: You MUST enable Xcode Tools MCP in Xcode settings:

1. Open Xcode > Settings (⌘,)
2. Select Intelligence in the sidebar
3. Under Model Context Protocol, toggle Xcode Tools ON

If you see "Found 0 tools" in your MCP client logs, this setting is not enabled.

Cursor Quick Setup

If you use Cursor, no installation is needed — just add this to ~/.cursor/mcp.json:

Broker mode (Recommended):

{
  "mcpServers": {
    "xcode-tools": {
      "command": "uvx",
      "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper", "--broker"]
    }
  }
}

With Web UI dashboard (optional — adds real-time monitoring at http://localhost:8080):

{
  "mcpServers": {
    "xcode-tools": {
      "command": "uvx",
      "args": [
        "--from",
        "mcpbridge-wrapper[webui]",
        "mcpbridge-wrapper",
        "--broker",
        "--web-ui",
        "--web-ui-config",
        "/Users/YOUR_USERNAME/.mcpbridge_wrapper/webui.json"
      ]
    }
  }
}

Direct mode (Alternative):

{
  "mcpServers": {
    "xcode-tools": {
      "command": "uvx",
      "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"]
    }
  }
}

If you upgrade and want to confirm the currently running dashboard process version:

PORT=8080
PID=$(lsof -tiTCP:$PORT -sTCP:LISTEN | head -n1)
PY=$(ps -p "$PID" -o command= | awk '{print $1}')
"$PY" -c 'import importlib.metadata as m; print(m.version("mcpbridge-wrapper"))'

If needed, do a one-time refresh start:

uvx --refresh --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080

Restart Cursor and you're done. For other clients or installation methods, read on.

Broker Mode

Broker mode lets multiple short

... View full README on GitHub