Xcode MCP Bridge Wrapper

You can use the Xcode MCP Bridge Wrapper to ensure Xcode 26.3’s MCP bridge talks to strict MCP clients like Cursor without missing required structured content. This wrapper intercepts responses and copies data from content into structuredContent, delivering MCP-compliant messages while letting you leverage Xcode’s MCP capabilities in a variety of tooling scenarios.

How to use

After you configure one of the supported MCP server launch methods, you can invoke your MCP clients to access Xcode tools through the wrapper. Use the wrapper as you would use a standard MCP server, but expect compliant responses from all clients that rely on the structuredContent field when outputSchema is declared. Typical workflows include building projects, running tests, and locating files or build errors with your preferred MCP client.

How to install

Prerequisites you need before installation are:

• macOS with Xcode 26.3 or newer
• Python 3.7 or newer
• Xcode Tools MCP Server enabled in Xcode settings (required for strict MCP clients to connect)

Choose an installation path that matches your workflow.

Option A: Using uvx (Recommended)

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

Additional setup options

Option B: Via MCP Registry

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

Option C: Using pip

Optionally, you can install the wrapper via Python’s package manager and run the wrapper binary directly.

pip install mcpbridge-wrapper

Then run mcpbridge-wrapper or xcodemcpwrapper as needed.

## Option D: Manual installation (Development)

If you prefer to build from source, clone the repository and install the project locally.

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

Add the local bin directory to your PATH.

Uninstallation

To remove the wrapper from your system, run the uninstallation script.

./scripts/uninstall.sh

Optional flags: --dry-run or -n to show what would be removed, --yes or -y to skip confirmation.

## Configuration

Configure your MCP clients to use the wrapper as the MCP server entry point. The following examples show common configuration patterns for Cursor and for a direct stdio integration.

## Cursor configuration (stdio)

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

## Direct stdio setup with a local wrapper

{ "mcpServers": { "xcode-tools": { "command": "xcodemcpwrapper", "args": [] } } }

## If you install via uvx or locally installed wrapper

When using a locally installed wrapper like `xcodemcpwrapper`, ensure the binary is in your PATH and you reference it by name in your configuration.

## Security and maintenance notes

Keep your Xcode and MCP client tools up to date. If you enable automatic updates for uvx or MCP helpers, monitor the wrapper for compatibility with future MCP protocol changes.

## Troubleshooting

If you encounter issues where MCP clients report non-compliant responses, verify that you are using a wrapper instance that is active and reachable by the client, and that Xcode Tools MCP is enabled in Xcode settings.

## Notes on usage scenarios

Typical scenarios include building projects, running tests, discovering project files, and surfacing build errors through MCP clients with guaranteed structuredContent availability.

## Available tools

### Content to structuredContent transformer

Intercepts MCP responses from xcrun mcpbridge and copies the data from content into structuredContent to satisfy the MCP specification when outputSchema is declared.