XcodeMCPKit

日本語

An MCP proxy for Xcode MCP (mcpbridge).
Designed so the Xcode permission dialog appears once when the proxy starts.

Quick Start

1. Start the proxy server

   xcode-mcp-proxy-server

2. Click Allow in Xcode’s permission dialog

Architecture

See Architecture for the process overview.

Installation

1. Install the binaries

Build from source

swift run -c release xcode-mcp-proxy-install

Install from GitHub Releases

Each release tag (v*) publishes:

• xcode-mcp-proxy.tar.gz (universal binary)
• xcode-mcp-proxy-darwin-arm64.tar.gz
• xcode-mcp-proxy-darwin-x86_64.tar.gz
• SHA256SUMS.txt

Example:

VERSION=v0.1.0
BASE_URL="https://github.com/lynnswap/XcodeMCPKit/releases/download/${VERSION}"

ARCHIVE="xcode-mcp-proxy.tar.gz"
curl -fL -O "${BASE_URL}/${ARCHIVE}"
curl -fL -O "${BASE_URL}/SHA256SUMS.txt"
grep "  ${ARCHIVE}\$" SHA256SUMS.txt | shasum -a 256 -c

tar -xzf "${ARCHIVE}"
mkdir -p "${HOME}/.local/bin"
cp bin/* "${HOME}/.local/bin/"
chmod +x "${HOME}/.local/bin/xcode-mcp-proxy" \
         "${HOME}/.local/bin/xcode-mcp-proxy-server" \
         "${HOME}/.local/bin/xcode-mcp-proxy-install"

If you prefer a platform-specific archive, choose one of:

• xcode-mcp-proxy.tar.gz: universal binary
• xcode-mcp-proxy-darwin-arm64.tar.gz: Apple Silicon
• xcode-mcp-proxy-darwin-x86_64.tar.gz: Intel

Optional: change the installation destination

./.build/release/xcode-mcp-proxy-install --prefix "$HOME/.local"
# or
./.build/release/xcode-mcp-proxy-install --bindir "$HOME/bin"

2. Add the install directory to your PATH

By default, xcode-mcp-proxy and xcode-mcp-proxy-server are installed to ~/.local/bin.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

3. Register the proxy in your MCP client

Replace xcrun mcpbridge with one of the following:

Codex

codex mcp remove xcode
# Recommended: Streamable HTTP
codex mcp add xcode --url http://localhost:8765/mcp

# Alternative: STDIO
codex mcp add xcode -- xcode-mcp-proxy

Claude Code

claude mcp remove xcode
claude mcp add --transport stdio xcode -- xcode-mcp-proxy

Usage

Proxy Server: xcode-mcp-proxy-server

See Quick Start for how to launch.

Defaults

• command: xcrun
• args: mcpbridge
• upstream processes: 1 (spawns multiple mcpbridge processes when increased)
• listen: localhost:8765
• request timeout: 300 seconds (0 disables)
• requests sharing the same MCP session are forwarded FIFO, one at a time
• max body size: 1048576 bytes
• initialization: eager at startup
• discovery: ~/Library/Caches/XcodeMCPProxy/endpoint.json

Options

Option	Description
--upstream-command cmd	mcpbridge command
--upstream-args a,b,c	mcpbridge args (comma-separated)
--upstream-arg value	Append a single mcpbridge arg
--upstream-processes n	Spawn n upstream mcpbridge processes (default: 1, max: 10)
--session-id id	Explicit Xcode MCP session ID
--max-body-bytes n	Max request body size
--request-timeout seconds	Request timeout (0 disables non-initialize timeouts; initialize still uses a bounded handshake timeout)
--config path	Path to proxy config TOML for overriding the upstream handshake
--refresh-code-issues-mode mode	Serve XcodeRefreshCodeIssuesInFile via proxy navigator issues (proxy, default) or pass through to Xcode live diagnostics (upstream)
--force-restart	If the listen port is in use, terminate an existing xcode-mcp-proxy-server and restart

Environment Variables

Variable	Description
LISTEN	Listen address; example: 127.0.0.1:8765
HOST	Listen host; used with PORT when LISTEN is unset
PORT	Listen port; used with HOST when LISTEN is unset
MCP_XCODE_PID	Passed through to upstream mcpbridge; the proxy itself does not parse it
MCP_XCODE_SESSION_ID	Optional explicit upstream session ID
MCP_XCODE_CONFIG	Proxy config TOML path; --config takes precedence
MCP_XCODE_REFRESH_CODE_ISSUES_MODE	proxy or upstream
MCP_LOG_LEVEL	Log level: trace, debug, info, notice, warning, error, critical

Logs are written to stderr.

Proxy Config

Key	Type	Default
upstream_handshake.protocolVersion	string	"2025-03-26"
upstream_handshake.clientName	string	"XcodeMCPKit"
upstream_handshake.clientVersion	string	"dev"
upstream_handshake.capabilities	table	{}

If clientVersion is omitted, the proxy auto-resolves it from the Xcode IDEChat*Version entry matching clientName when available.

Adapter: xcode-mcp-proxy

Options

Option	Description
--request-timeout seconds	HTTP request timeout (0 disables)
--url url	Explicit upstream URL (example: http://localhost:9000/mcp)

Environment Variables

Variable	Description
XCODE_MCP_PROXY_ENDPOINT	Override upstream URL; --url takes precedence

Troubleshooting

Troubleshooting

References

• MCP / Xcode MCP Benchmark Notes
• MCP Connection Permission Dialog Investigation

License

LICENSE