pi-xcode-mcp

Connect Pi to Xcode's built-in MCP server using Pi 0.99's native MCP client, with Xcode-specific wrappers for SwiftUI previews, workspace selection, builds, and diagnostics.

Requires Pi 0.99.0 or later. Earlier Pi versions do not provide the native MCP APIs used by this package.

The primary goal is simple: ask Pi to render a SwiftUI preview and inspect the actual screenshot.

Why this package still exists

Pi now owns the generic MCP transport and lifecycle. This package adds the Xcode-specific behavior that raw MCP configuration does not provide:

• Registers xcrun mcpbridge through pi.registerMcpServer().
• Adds xcode_render_preview, which reads Xcode's previewSnapshotPath and attaches the image to Pi.
• Automatically resolves workspaceIdentifier from the workspace matching Pi's current directory.
• Adds xcode_build, which fetches build logs and, when Xcode advertises the tool, Issue Navigator diagnostics on failure.
• Treats logical build, test, and preview failures as failed Pi tool results even when the MCP transport itself succeeded.
• Keeps the raw Xcode MCP tools available through Pi's token-efficient codemode exposure.

Pi's built-in /mcp interface handles connection status, errors, reconnecting, enabling, and disabling the server.

Requirements

• macOS
• Pi 0.99.0 or later
• Xcode 27 or later
• Either an open Xcode project/workspace or a running headless MCP service

Check that Apple's MCP bridge is available:

xcrun --find mcpbridge

If this fails, make sure xcode-select points to the full Xcode app rather than Command Line Tools:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch

Enable Xcode MCP

Xcode app

1. Open Xcode > Settings > Intelligence.
2. Enable Model Context Protocol / Xcode Tools.
3. Open your project or workspace in Xcode.
4. When Xcode asks to allow the external MCP connection, click Allow.

Headless Xcode 27

Xcode 27 can expose the same tools without running the Xcode UI. Enabling the service changes a system permission and requires administrator approval; this package never enables it or runs sudo automatically.

Enable it once, then start it:

sudo xcrun mcp-server enable
xcrun mcp-server start
xcrun mcp-server status

Keep the default per-agent approval mode. Do not use --unsafe-always-allow-all-agents unless you understand that it grants every local process access to every reachable Xcode project.

In headless mode, the first XcodeOpenWorkspace call asks you to approve the agent and project folder. The MCP server inherits DEVELOPER_DIR, so you can target a non-default Xcode installation:

export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer

Installation

Selected project only

This is the recommended setup for selectively enabling Xcode MCP:

cd /path/to/project
pi install -l npm:pi-xcode-mcp

The project-local Pi settings load the package only in that project. The package then registers its native MCP server for that session; a separate .pi/mcp.json entry is not required.

Global installation

pi install npm:pi-xcode-mcp

Use global installation only if you want Pi to attempt the Xcode MCP connection in every project where the package is loaded.

If Pi is already running, reload resources:

/reload

Install from a local checkout

git clone https://github.com/igorkulman/pi-xcode-mcp.git
cd pi-xcode-mcp
pi install .

Try without installing

pi -e /absolute/path/to/pi-xcode-mcp

Quick start

1. Open your app or package in Xcode, or start Xcode's headless MCP service.
2. Open Pi from the same project/workspace directory.
3. Run /mcp and confirm that the xcode server is connected.
4. In headless mode, use the native XcodeOpenWorkspace MCP tool if no workspace is active.
5. Ask Pi:

Render the SwiftUI preview in DeviceListView and tell me what you see.

Pi uses xcode_render_preview, resolves the matching workspace, calls Xcode's native RenderPreview MCP tool, reads the generated snapshot, and inspects the attached image.

If the source file contains multiple previews:

Render preview index 1 in DeviceListView.

Tools

Xcode-specific wrappers

Native Xcode MCP tools

Xcode's advertised tools are registered by Pi as mcp__xcode__<tool>, for example:

• mcp__xcode__BuildProject
• mcp__xcode__RunAllTests
• mcp__xcode__RunSomeTests
• mcp__xcode__DocumentationSearch
• mcp__xcode__XcodeOpenWorkspace
• mcp__xcode__XcodeListWorkspaces

They use codemode exposure by default, keeping the complete Xcode tool set out of the model's direct tool declarations while remaining callable by Pi and by this package's wrappers.

The available tools are determined by the installed Xcode version. Inspect them with /mcp rather than relying on a fixed package-maintained mirror.

Example workflows

Verify a SwiftUI change visually

I changed DeviceListView. Render its SwiftUI preview and compare the screenshot with the expected layout.

Build and inspect errors

Build the active Xcode scheme and summarize any errors.

xcode_build builds through the matching workspace and retrieves GetBuildLog plus Issue Navigator diagnostics when those tools are advertised by the installed Xcode version.

Search Apple documentation

Use Xcode MCP to search Apple documentation for the current NavigationSplitView API.

Pi can call the native DocumentationSearch tool through codemode.

MCP management

Use Pi's built-in interface:

/mcp
/mcp reconnect xcode

From the shell, project and global configured servers can be inspected with:

pi mcp list

The xcode server appears as extension-provided because this package registers it at runtime. Pi's shell command does not load extensions, so use /mcp inside a Pi session to inspect this package's registration.

If a project .pi/mcp.json defines another server named xcode, that configured entry takes precedence over this package's registration.

Troubleshooting

The xcode server does not connect

Run /mcp, select xcode, and inspect the complete connection error. Also verify:

xcrun --find mcpbridge
xcrun mcp-server status

For the Xcode app, make sure Xcode is running, the project is open, Xcode MCP is enabled under Settings > Intelligence, and the connection prompt was approved.

No workspace is open

Use Xcode's native XcodeOpenWorkspace MCP tool with the absolute project or workspace path. In headless mode, approve the folder when macOS asks.

Preview rendering times out

Open the file in Xcode and make sure its preview can render there. Large projects may need an initial build before previews become available through MCP. The package configures a 120-second MCP request timeout.

Preview renders but Pi cannot see the screenshot

xcode_render_preview reads the local previewSnapshotPath returned by Xcode and attaches it as an image. If Xcode removes the temporary file before it can be read, the result includes the path and read error.

Multiple Xcode workspaces are open

The wrapper prefers the workspace path matching Pi's current directory. If it cannot choose uniquely, pass workspaceIdentifier explicitly or start Pi from the intended workspace directory.

Development

Install dependencies:

npm install

Run tests and type-check:

npm test
npm run typecheck

Try the package locally with Pi's built-in MCP support enabled:

pi --no-extensions -e builtin:mcp -e .

Pack without publishing:

npm pack --dry-run

Security

Pi extensions run with your local user permissions. This package asks Pi's native MCP client to start Apple's xcrun mcpbridge, and the active model can call tools exposed by Xcode. Only use it with models and projects you trust, and prefer headless mode's per-agent and per-folder approvals over unsafe global access.

The package never enables or starts Xcode's headless service and never invokes sudo.

License

MIT