mcpbridge-wrapper 0.3.3

Python wrapper for xcrun mcpbridge that adds structuredContent to MCP responses

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.7+
• 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:

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

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",
        "--web-ui",
        "--web-ui-port",
        "8080"
      ]
    }
  }
}

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

Python Environment Setup (Development)

If you plan to run make install, pytest, or other development commands, create and activate a virtual environment first. This avoids Homebrew Python's externally-managed-environment (PEP 668) error.

cd XcodeMCPWrapper
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
make install

Quick checks:

which python3
which pip

Both should point to .venv/bin/... while the environment is active.

Installation

Option 1: Using uvx (Recommended - Easiest)

The fastest way to install is using uvx (requires uv to be installed):

# No manual installation needed - uvx will automatically download and run
uvx --from mcpbridge-wrapper mcpbridge-wrapper

Or add to your MCP client configuration directly (see configuration sections below).

Option 2: Via MCP Registry

If your MCP client supports the MCP Registry:

Server name: io.github.SoundBlaster/xcode-mcpbridge-wrapper

# Using mcp-publisher CLI
mcp-publisher install io.github.SoundBlaster/xcode-mcpbridge-wrapper

Option 3: Using pip

python3 -m pip install mcpbridge-wrapper

Then use mcpbridge-wrapper or xcodemcpwrapper command.

Option 4: Manual Installation (via install script)

git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git
cd XcodeMCPWrapper
./scripts/install.sh

The install script creates a virtual environment, installs the package, and places a wrapper at ~/bin/xcodemcpwrapper.

If you plan to use --web-ui MCP args, install Web UI extras explicitly:

./scripts/install.sh --webui

Add the following to your ~/.bashrc or ~/.zshrc:

export PATH="$HOME/bin:$PATH"

Then reload:

source ~/.zshrc
# or
. ~/.zshrc

Option 5: Local Development (venv)

For development or if you want to run directly from the cloned repository:

git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git
cd XcodeMCPWrapper
python3 -m venv .venv
source .venv/bin/activate
make install          # or: make install-webui (for Web UI support)

The entry point is .venv/bin/mcpbridge-wrapper. Use the full absolute path when configuring MCP clients (see configuration sections below).

Uninstallation

To remove xcodemcpwrapper from your system:

./scripts/uninstall.sh

Options:

• --dry-run or -n: Show what would be removed without removing
• --yes or -y: Skip confirmation prompt

Configuration

Cursor

For uvx setup (recommended), see Cursor Quick Setup above.

Using manual installation:

{
  "mcpServers": {
    "xcode-tools": {
      "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
      "args": []
    }
  }
}

Using manual installation with Web UI (Optional):

Requires installing with ./scripts/install.sh --webui (or equivalent .[webui] dependencies).

{
  "mcpServers": {
    "xcode-tools": {
      "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
      "args": ["--web-ui", "--web-ui-port", "8080"]
    }
  }
}

Using local development (venv):

{
  "mcpServers": {
    "xcode-tools": {
      "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper"
    }
  }
}

Using local development with Web UI (Optional):

{
  "mcpServers": {
    "xcode-tools": {
      "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper",
      "args": ["--web-ui", "--web-ui-port", "8080"]
    }
  }
}

Claude Code

Using uvx (Recommended):

claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper

Using uvx with Web UI (Optional):

claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080

Using manual installation:

claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper

Using manual installation with Web UI (Optional): Requires installing with ./scripts/install.sh --webui (or equivalent .[webui] dependencies).

claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080

Using local development (venv):

claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper

Using local development with Web UI (Optional):

claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --web-ui --web-ui-port 8080

Codex CLI

Using uvx (Recommended):

codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper

Using uvx with Web UI (Optional):

codex mcp add xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080

Using manual installation:

codex mcp add xcode -- ~/bin/xcodemcpwrapper

Using manual installation with Web UI (Optional): Requires installing with ./scripts/install.sh --webui (or equivalent .[webui] dependencies).

codex mcp add xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080

Using local development (venv):

codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper

Using local development with Web UI (Optional):

codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --web-ui --web-ui-port 8080

Zed Agent

Using uvx (Recommended):

Edit ~/.zed/settings.json:

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

Using uvx with Web UI (Optional):

{
  "xcode-tools": {
    "command": "uvx",
    "args": [
      "--from",
      "mcpbridge-wrapper[webui]",
      "mcpbridge-wrapper",
      "--web-ui",
      "--web-ui-port",
      "8080"
    ],
    "env": {}
  }
}

Using manual installation:

{
  "xcode-tools": {
    "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
    "args": [],
    "env": {}
  }
}

Using manual installation with Web UI (Optional): Requires installing with ./scripts/install.sh --webui (or equivalent .[webui] dependencies).

{
  "xcode-tools": {
    "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
    "args": ["--web-ui", "--web-ui-port", "8080"],
    "env": {}
  }
}

Using local development (venv):

{
  "xcode-tools": {
    "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper",
    "args": [],
    "env": {}
  }
}

Using local development with Web UI (Optional):

{
  "xcode-tools": {
    "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper",
    "args": ["--web-ui", "--web-ui-port", "8080"],
    "env": {}
  }
}

Kimi CLI

Using uvx (Recommended):

Edit ~/.kimi/mcp.json:

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

Using manual installation:

{
  "xcode-tools": {
    "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
    "args": [],
    "env": {}
  }
}

Usage

Once configured, ask your AI assistant to use Xcode tools:

"Build my project"
"Run the tests"
"Find all Swift files in the project"
"Show me the build errors"

Web UI Dashboard (Optional)

The wrapper includes an optional Web UI dashboard for real-time monitoring and audit logging:

# Start with Web UI
make webui

# Or directly
python -m mcpbridge_wrapper --web-ui --web-ui-port 8080

Features:

• Real-time metrics: RPS, latency percentiles (p50, p95, p99), error rates
• Tool usage analytics: Visual charts of most frequently used tools
• Audit logging: Persistent log of all MCP tool calls with export (JSON/CSV)
• Request inspector: Live log stream with filtering

Open http://localhost:8080 in your browser to view the dashboard.

See Web UI Setup Guide for detailed configuration.

Documentation

• Installation Guide
• Web UI Dashboard - Real-time monitoring and audit logging
• Cursor Setup
• Claude Code Setup
• Codex CLI Setup
• Troubleshooting
• Tools Reference
• Architecture
• Contributing - Development guide and quality gates

Development

See CONTRIBUTING.md for development setup and contribution guidelines.

Quick quality gate check:

make test      # Run tests with coverage
make lint      # Run ruff linter
make typecheck # Run mypy type checker

Or run all gates:

make test && make lint && make typecheck

Performance

• Overhead: <0.01ms per transformation
• Memory: <10MB footprint
• Coverage: 98.2% test coverage

License

MIT License - see LICENSE for details.

Acknowledgments

• Apple's Xcode team for the MCP bridge functionality
• The MCP protocol specification
• The Cursor, Claude, and Codex teams for AI-powered development tools