X Code MCP Service

XCodeMCPService

中文文档

MCP Forward Bridge — Keep xcrun mcpbridge running in the background and forward MCP requests via Streamable HTTP.

Every MCP client connection spawns a new xcrun mcpbridge process, triggering an Xcode authorization prompt. This project keeps a single xcrun mcpbridge process alive and aggregates forwarded requests, eliminating repeated authorization.

MCP Client ──HTTP/POST──▶ XCodeMCPService ──stdio──▶ MCP Server (xcrun mcpbridge)
           ◀──JSON-RPC───                  ◀──pipe──

Features

• Multi-server aggregation — Manage multiple MCP subprocesses and auto-aggregate downstream capabilities; tool names stay original in single-server mode and switch to namespace prefixes (serverName__toolName) only when multiple servers are configured
• Streamable HTTP Transport — Lightweight HTTP server based on NWListener, providing /mcp endpoint, localhost only
• Session management — Independent session per client with secure token identification
• Process lifecycle — Crash detection + exponential backoff auto-restart
• macOS status bar app — Visual service status, one-click start/stop

Requirements

• macOS 15.0+
• Swift 6.0+
• Xcode 26.3+ (xcrun mcpbridge support)

Installation

git clone git@github.com:ljh740/XCodeMCPService.git
cd XCodeMCPService

# Build .app (recommended)
bash build-app.sh

# Install to Applications
cp -r "build/XCode MCP Service.app" /Applications/

Build output is at build/XCode MCP Service.app, containing:

The packaging script also produces:

You can locate standalone binaries with swift build -c release --show-bin-path.

Quick Start

1. Create config file

mkdir -p ~/Library/Application\ Support/XCodeMCPService

{
  "bridge": {
    "port": 13339,
    "host": "127.0.0.1",
    "timeout": 30000,
    "logLevel": "info"
  },
  "servers": [
    {
      "name": "xcode-tools",
      "command": "xcrun",
      "args": ["mcpbridge"],
      "enabled": true
    }
  ]
}

Save as ~/Library/Application Support/XCodeMCPService/config.json.

Without a config file, the service uses built-in defaults (port 13339, auto-start xcrun mcpbridge). A default config file is created on first launch.

2. Start the service

# Via .app (status bar app)
open "/Applications/XCode MCP Service.app"

# Or via CLI
BIN_DIR="$(swift build -c release --show-bin-path)"
"$BIN_DIR/XCodeMCPService"

# Specify config file
"$BIN_DIR/XCodeMCPService" --config /path/to/config.json

# Via environment variable
CONFIG_PATH=/path/to/config.json "$BIN_DIR/XCodeMCPService"

3. Configure MCP client

Add to your MCP client configuration:

{
  "mcpServers": {
    "local-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:13339/mcp"
    }
  }
}

Configuration Reference

BridgeConfig

ServerConfig

Config file lookup order

1. --config CLI argument
2. CONFIG_PATH environment variable
3. ~/Library/Application Support/XCodeMCPService/config.json
4. Built-in defaults (auto-written to default path on first launch)

Logs

Log files are stored by date in ~/Library/Application Support/XCodeMCPService/logs/ as yyyy-MM-dd.log. Also output to stderr.

Testing

swift test

83 tests covering: HTTP parsing/serialization/routing, session management, ResponseQueue, ID mapping, process lifecycle management, etc.

CI/CD

• .github/workflows/ci.yml: runs swift build -c release and swift test --parallel on every push and pull request.
• .github/workflows/release.yml: runs bash build-app.sh on every v* tag push or manual dispatch, then uploads the .app bundle, dmg, zip, and SHA-256 checksum files as workflow artifacts.
• Tag builds also publish build/XCodeMCPService-.dmg, build/XCodeMCPService-.dmg.sha256, build/XCodeMCPService-.zip, and build/XCodeMCPService-.zip.sha256 to the matching GitHub Release.

License

MIT License

Acknowledgments

• Model Context Protocol — MCP specification
• swift-sdk — MCP Swift SDK