Xcode Errors MCP Server

An MCP (Model Context Protocol) server that bridges Xcode and Cursor, giving an LLM real-time access to build errors, warnings, and console output directly within your editor.

⚠️ This repo is still under development and things may break without warning.

Features

• Real-time Error Monitoring: Automatically detects and parses Xcode build errors and warnings

• Debug Log Streaming: Captures and streams Xcode console output and debug logs

• Project Analysis: Analyzes Swift/SwiftUI projects for common issues

• File Integration: Provides tools to read project files for diagnostic context

• Live Updates: Monitors DerivedData for new build results

Related MCP server: Xcode Diagnostics MCP Plugin

How It Works

1. DerivedData Monitoring: Watches Xcode's DerivedData directory for new build logs

2. Log Parsing: Extracts structured diagnostic information from build logs

3. Console Integration: Captures real-time debug output from Xcode's console

4. MCP Interface: Exposes diagnostics and file operations through MCP protocol

5. Cursor Integration: Allows Cursor to query errors and make fixes automatically

Architecture

Xcode Build System
       ↓
DerivedData Logs → MCP Server → Cursor/LLM
       ↓                ↑
Console Output ←--------┘

Installation

1. Clone this repository:

   git clone https://github.com/YOUR_USERNAME/xcode-errors-mcp.git  # Replace YOUR_USERNAME with actual GitHub username
   cd xcode-errors-mcp

2. Run the installation script:

   ./install.sh

3. Configure Cursor MCP settings:

   • Open Cursor settings

   • Navigate to MCP configuration

   • Copy the contents of cursor_config.json to your MCP configuration

   • IMPORTANT: Replace /path/to/your/xcode-errors-mcp with your actual installation path

   • Example: If you cloned to /Users/yourname/xcode-errors-mcp, update all paths accordingly

4. Restart Cursor completely (⌘+Q and reopen) to activate the MCP server connection

Usage

Once connected, Cursor can:

• Query current build errors: get_build_errors()

• Monitor debug output: get_console_logs()

• Analyze project structure: analyze_project()

• Read project files: read_project_file()

Quick Start

1. Install dependencies:

   ./install.sh

2. Test the installation:

   python3 examples/test_parser.py

3. Configure Cursor:

   • Open Cursor Settings → Features → Model Context Protocol

   • Copy the contents of cursor_config.json to your MCP configuration

   • CRITICAL: Replace all instances of /path/to/your/xcode-errors-mcp with your actual installation path

   • Example configuration for installation in /Users/yourname/xcode-errors-mcp:

     {
       "mcpServers": {
         "xcode-errors": {
           "command": "/Users/yourname/xcode-errors-mcp/venv/bin/python",
           "args": [
             "/Users/yourname/xcode-errors-mcp/src/xcode_mcp_server.py"
           ],
           "env": {
             "PYTHONPATH": "/Users/yourname/xcode-errors-mcp/src"
           }
         }
       }
     }

   • Restart Cursor completely (⌘+Q and reopen)

4. Verify it's working:

   • Check that the MCP server shows a green indicator in Cursor settings

   • If you see a red indicator, check TROUBLESHOOTING.md

5. Start using it:

   • Build a project in Xcode (to generate some logs)

   • In Cursor, you can now use tools like:

     • get_build_errors() - Get current build errors

     • get_console_logs() - Get debug output

     • list_recent_projects() - See your projects

     • analyze_project("ProjectName") - Analyze issues

Configuration Placeholders

After cloning this repository, you must update the following placeholders with your actual paths:

1. cursor_config.json

Replace /path/to/your/xcode-errors-mcp with your installation directory:

• command: Path to your Python virtual environment

• args: Path to the MCP server script

• env.PYTHONPATH: Path to the src directory

2. Finding Your Installation Path

cd xcode-errors-mcp
pwd  # This shows your full installation path

3. Example Configuration

If you installed to /Users/yourname/xcode-errors-mcp, your cursor_config.json should look like:

{
  "mcpServers": {
    "xcode-errors": {
      "command": "/Users/yourname/xcode-errors-mcp/venv/bin/python",
      "args": [
        "/Users/yourname/xcode-errors-mcp/src/xcode_mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": "/Users/yourname/xcode-errors-mcp/src"
      }
    }
  }
}

Security Considerations

This server gives an LLM read access to project files and write access for saving device logs, so access is treated like any other privilege grant:

• Transport: runs locally over stdio — nothing is exposed on the network

• Home-directory containment: file operations are restricted to your home directory; requests for paths outside it (e.g., /etc/passwd) are rejected at the server level

• Dotfile protection: the server refuses any path where a component starts with ., blocking access to ~/.ssh, ~/.aws, and similar credential stores

• Read-only for source: read_project_file is read-only; there is no write_file tool — the LLM cannot overwrite your source through this server

• Review before committing: like any AI-assisted workflow, treat suggested edits as a diff to review, not a push-button deploy

Known gaps / roadmap:

• Path scoping is currently home-directory-wide rather than scoped to a specific Xcode project root — a tighter allow-list (e.g., ~/Developer/) or per-session project root detection would reduce the blast radius further

• No dry-run mode for save_device_logs; the output path is validated but not previewed before writing

Development Status

✅ Core functionality implemented and tested — WIP, things may change without notice.