XcodeMCPWrapper

XcodeMCPWrapper is a Python-based wrapper that makes Xcode 26.3+ MCP bridge compliant tools work with MCP clients like Cursor and Codex CLI. It does this by intercepting responses from xcrun mcpbridge and copying content data into the required structuredContent field, ensuring full MCP specification compatibility. Once running, you can use it as a brokered or direct bridge, enabling MCP sessions from editors or command line clients to interact with macOS/Xcode MCP tools without protocol errors. The repository emphasizes ease of use via uvx (the universal VPM/XV wrapper) so you can start the wrapper without a manual Python install, and it provides quick-start snippets for Cursor configuration in broker or direct modes.

Typical use cases include enabling Cursor, Codex CLI, or other MCP clients to talk to Xcode tools through the wrapper, in either broker mode (shared upstream session) or direct mode (one-to-one session). If you prefer a no-install approach, install uvx and point it at the mcpbridge-wrapper as shown in the Quick Start examples. The wrapper is designed to be developer-friendly and includes guidance for verifying the current version, refreshing dashboards, and integrating Web UI when needed.

Prerequisites:

• macOS with Xcode 26.3+ installed
• Python 3.9+ (for development or if not using uvx)
• uv (for uvx) installed on your system if you are following the recommended install path

Option A – Install via uvx (recommended, easiest):

1. Ensure uvx is installed on your system. If not, follow uvx installation instructions from https://github.com/astral-sh/uv.
2. Run the wrapper using uvx, which will automatically download and run mcpbridge-wrapper:

uvx --from mcpbridge-wrapper mcpbridge-wrapper

Option B – Local development environment (Python) (if you plan to run or develop locally):

1. Clone the repository and navigate into it.
2. Create and activate a virtual environment:

cd XcodeMCPWrapper
python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies and the package in editable mode (if applicable):

python3 -m pip install --upgrade pip
python3 -m pip install -e .

4. Run the Python-based wrapper directly (if you’re not using uvx):

python3 -m mcpbridge_wrapper

Prerequisites are focused on enabling MCP tool sessions through uvx or a local Python setup, depending on your preferred workflow.

Tips and caveats:

• Ensure Xcode Tools MCP is enabled in Xcode (Settings > Intelligence > Model Context Protocol > Xcode Tools ON) to avoid missing tools in MCP client logs.
• If you see “Found 0 tools” in MCP client logs, the Xcode Tools MCP setting may not be enabled.
• The wrapper is intended to be drop-in compatible with MCP clients like Cursor and Codex CLI; if you’re using a broker mode setup, consult the broker-mode guides referenced in the project for optimal session management.
• When using uvx in broker mode, you can add --web-ui or --web-ui-config to expose a dashboard for monitoring, provided you have the appropriate port available.
• For development or troubleshooting, you can verify the currently running wrapper version via Python’s importlib.metadata (as shown in the Quick Start), which helps confirm you’re using the expected release.
• If you upgrade or change modes, restarting your MCP clients (and potentially the broker) may be required to apply changes.