CrashPoint iOS MCP

A TypeScript MCP (Model Context Protocol) server that wraps the CrashPoint iOS crash analysis pipeline as MCP tools. Use it with Claude Desktop, Cursor, and other MCP clients to export, symbolicate, analyze, and report iOS/macOS crash logs — all through natural language.

Also includes a standalone CLI (crashpoint-ios-cli) for scheduled runs without an AI client.

What It Does

CrashPoint iOS MCP gives your AI assistant the ability to:

1. Export .crash files from Xcode Organizer .xccrashpoint bundles

2. Save Apptics crash data as .crash files for unified processing

3. Symbolicate crashes using Xcode's symbolicatecrash tool and your .dSYM bundle

4. Analyze & group symbolicated crashes by unique signature, device, iOS version, and app version

5. Track fixes locally so your team can mark crash types as resolved

6. Notify Zoho Cliq with crash report summaries via webhook

7. Report to Zoho Projects — prepare structured bug data for creation/updates

8. Run the full pipeline end-to-end with Apptics, Cliq, and Zoho Projects integration

Related MCP server: Log Analyzer MCP

Prerequisites

• macOS (required for Xcode's symbolicatecrash and dwarfdump)

• Node.js 18+

• Xcode CLI tools (xcode-select --install)

• A .dSYM bundle for your app

• Xcode Organizer crash data (.xccrashpoint files)

Installation

git clone https://github.com/maanasa-s-5539/CrashPoint-IOS-MCP.git
cd CrashPoint-IOS-MCP
npm install
npm run build

Configuration

Copy crashpoint.config.example.json from the repo root to <ParentHolderFolder>/crashpoint.config.json and fill in your values:

cp crashpoint.config.example.json /path/to/ParentHolderFolder/crashpoint.config.json

This JSON config file is the single source of truth for all user configuration — you only need to edit this one file. The .mcp.json (used by Claude CLI for the automation pipeline) and the launchd .plist (for scheduled daily runs) are auto-generated from it by setup_folders and by run_crash_pipeline.sh on first run.

When both the JSON config file and environment variables provide the same key, environment variables win — values in process.env override values from the JSON config file. This means MCP client env blocks (or a .env file used as a fallback) can always override the JSON config.

Complete crashpoint.config.json example

{
  "CRASH_ANALYSIS_PARENT": "/path/to/ParentHolderFolder",
  "CLAUDE_CLI_PATH": "/Users/name/.local/bin/claude",

  "DSYM_PATH": "/path/to/MyApp.app.dSYM",
  "MASTER_BRANCH_PATH": "/path/to/master",
  "DEV_BRANCH_PATH": "/path/to/dev",

  "CRASH_INPUT_DIR": "",
  "CRASH_VERSIONS": "1.0.0",
  "CRASH_DATE_OFFSET": "4",
  "CRASH_NUM_DAYS": "1",
  "SCHEDULED_RUN_TIME": "11:00",

  "APP_DISPLAY_NAME": "MyApp",
  "APPTICS_MCP_NAME": "apptics-mcp",
  "APPTICS_PORTAL_ID": "12345",
  "APPTICS_PROJECT_ID": "67890",
  "APPTICS_APP_NAME": "MyApp",

  "ZOHO_CLIQ_WEBHOOK_URL": "https://cliq.zoho.in/...",
  "ZOHO_PROJECTS_PORTAL_ID": "12345",
  "ZOHO_PROJECTS_PROJECT_ID": "67890",
  "ZOHO_BUG_STATUS_OPEN": "status-id-open",
  "ZOHO_BUG_STATUS_FIXED": "status-id-fixed",
  "ZOHO_BUG_SEVERITY_SHOWSTOPPER": "severity-id-showstopper",
  "ZOHO_BUG_SEVERITY_CRITICAL": "severity-id-critical",
  "ZOHO_BUG_SEVERITY_MAJOR": "severity-id-major",
  "ZOHO_BUG_SEVERITY_MINOR": "severity-id-minor",
  "ZOHO_BUG_SEVERITY_NONE": "severity-id-none",
  "ZOHO_BUG_APP_VERSION": "field-name",
  "ZOHO_BUG_NUM_OF_OCCURRENCES": "field-name"
}

Config key reference

MCP Client Configuration

All MCP clients use the same JSON block — only the config file path differs.

Block to add:

{
  "mcpServers": {
    "crashpoint-ios": {
      "command": "npx",
      "args": [
        "-p",
        "github:maanasa-s-5539/CrashPoint-IOS-MCP",
        "crashpoint-ios-core"
      ],
      "env": {
        "CRASH_INPUT_DIR": "/path/to/Xcode/Products/com.example.myapp/Crashes/Points",
        "CRASH_ANALYSIS_PARENT": "/path/to/ParentHolderFolder"
      }
    }
  }
}

Where to put it:

If the chosen file already contains an mcpServers object, add the "crashpoint-ios": { ... } entry inside the existing object instead of duplicating the key.

Replace /path/to/... with real absolute paths on your machine. CRASH_ANALYSIS_PARENT is required; CRASH_INPUT_DIR is optional and only needed when overriding the default Xcode crash input location.

All other values (paths, app name, etc.) are read automatically from crashpoint.config.json.

Restart Claude Desktop, Cursor, or start a new claude CLI session after saving the file.

Environment Variables

Only CRASH_ANALYSIS_PARENT is required as an environment variable — it tells the server where to find crashpoint.config.json. All other settings live in that config file.

Environment variables can still override any key from crashpoint.config.json (env always wins) if you need per-client overrides via MCP client env blocks.

Quick Start

There are two ways to run the CrashPoint pipeline. Choose the path that fits your workflow:

Path A: Claude Desktop / Cursor (zero manual setup)

The MCP tools automatically create the entire workspace on the very first run — no setup command needed beforehand.

1. Clone & build the repo (or install via npx — see Installation above).

2. Create your ParentHolderFolder and place a filled-in crashpoint.config.json inside it (see Configuration above).

3. Configure your MCP client with CRASH_ANALYSIS_PARENT pointing to your ParentHolderFolder (see the Cursor / Claude Desktop block in Configuration above).

4. Ask Claude to call run_full_pipeline — on the very first call, the MCP server detects that the workspace doesn't exist yet and automatically runs setup (creating all folders, copying prompt templates, generating run_crash_pipeline.sh with your real paths, and writing .mcp.json). No prior setup step is needed.

That's it. After the first run_full_pipeline (or run_basic_pipeline) call, the full workspace is ready and every subsequent call works without any additional configuration.

Path B: Terminal bash script (one-time setup required first)

The bash script at ParentHolderFolder/Automation/run_crash_pipeline.sh does not exist until a setup command generates it. The repo contains only a template (automation/run_crash_pipeline.sh) with <REPLACE_WITH_...> placeholders. The setup command replaces those placeholders with your real paths automatically — you never need to edit them manually.

# 1. Clone and build the repo
git clone https://github.com/maanasa-s-5539/CrashPoint-IOS-MCP.git
cd CrashPoint-IOS-MCP
npm install
npm run build

# 2. Create your ParentHolderFolder and fill in crashpoint.config.json
mkdir -p /path/to/ParentHolderFolder
cp crashpoint.config.example.json /path/to/ParentHolderFolder/crashpoint.config.json
# Edit /path/to/ParentHolderFolder/crashpoint.config.json with your real values

# 3. Run the setup command once — creates the folder structure AND generates
#    run_crash_pipeline.sh with your real paths automatically filled in
CRASH_ANALYSIS_PARENT=/path/to/ParentHolderFolder node dist/cli.js setup

# 4. Run the generated script (placeholders already replaced — no manual editing needed)
bash /path/to/ParentHolderFolder/Automation/run_crash_pipeline.sh

Note: The auto-setup block inside the generated bash script (which calls node dist/cli.js setup if folders are missing) is a safety net for subsequent runs — for example if folders were accidentally deleted. It is not the mechanism for the initial bootstrap. Step 3 above is the required first-time step.

Folder Structure

CrashPoint iOS MCP uses a ParentHolderFolder to organize crash data:

ParentHolderFolder/                   ← CRASH_ANALYSIS_PARENT
├── crashpoint.config.json            ← Single source of truth for all configuration
├── .mcp.json                         ← Auto-generated (do not edit manually)
├── MainCrashLogsFolder/
│   ├── XCodeCrashLogs/               ← Exported .crash files from Xcode Organizer
│   ├── AppticsCrashLogs/             ← Apptics SDK crash logs
│   └── OtherCrashLogs/              ← Other crash logs
├── SymbolicatedCrashLogsFolder/      ← Symbolicated .crash files
├── AnalyzedReportsFolder/            ← JSON + CSV analysis reports
├── StateMaintenance/                 ← Processed manifest + fix tracking
└── Automation/                       ← Pipeline scripts, prompts, and logs
    ├── run_crash_pipeline.sh         ← Generated by setup (placeholders auto-replaced)
    ├── daily_crash_pipeline_prompt_phase1.md
    ├── daily_crash_pipeline_prompt_phase2.md
    └── ScheduledRunLogs/

Using Claude Desktop / Cursor (MCP path): The folder structure is created automatically on the first call to run_full_pipeline or run_basic_pipeline — no manual setup step needed. The MCP server also generates Automation/run_crash_pipeline.sh with your real paths filled in as part of this auto-setup.

Using the terminal bash script: Run CRASH_ANALYSIS_PARENT=/path/to/ParentHolderFolder node dist/cli.js setup once to create the folder structure and generate Automation/run_crash_pipeline.sh with your real paths. After that, run bash /path/to/ParentHolderFolder/Automation/run_crash_pipeline.sh. You can also run setup_folders in Claude Desktop / Cursor to do the same thing interactively.

Available MCP Tools

For detailed parameter documentation, see Tool Parameters.

Standalone CLI

The CLI lets you run the crash analysis pipeline without an MCP client (useful for scheduled runs):

# Delete crash files older than a given date
node dist/cli.js clean --before-date 2026-03-01

# Delete analyzed report files in AnalyzedReportsFolder older than a given date
node dist/cli.js cleanup-reports --before-date 2026-03-01

# Create folder structure with symlinks
node dist/cli.js setup --master-branch /path/to/master --dev-branch /path/to/dev --dsym /path/to/MyApp.dSYM

# Validate a dSYM bundle and check UUID matches against crashes in MainCrashLogsFolder
node dist/cli.js verify-dsym
node dist/cli.js verify-dsym --crash-dir /path/to/MainCrashLogsFolder/XCodeCrashLogs/ --dsym /path/to/MyApp.dSYM

# Export crash logs from Xcode Organizer
node dist/cli.js export

# Export crashes filtered by date range
node dist/cli.js export --start-date 2026-03-01 --end-date 2026-03-20

# Symbolicate all crash files in MainCrashLogsFolder (XCodeCrashLogs, AppticsCrashLogs, OtherCrashLogs)
node dist/cli.js batch

# Symbolicate a single crash file
node dist/cli.js batch --file /path/to/crash.crash

# Analyze crashes and print JSON report (also auto-saves JSON + CSV to AnalyzedReportsFolder)
node dist/cli.js analyze

# Manage fix statuses (unified command)
node dist/cli.js fix-status --action set --signature "EXC_BAD_ACCESS SIGSEGV" --note "Fixed in PR #42"
node dist/cli.js fix-status --action unset --signature "EXC_BAD_ACCESS SIGSEGV"
node dist/cli.js fix-status --action list

# Run basic pipeline (export → symbolicate → analyze)
node dist/cli.js pipeline

# Remove all crash files and reports in one go
node dist/cli.js cleanup                  # delete everything
node dist/cli.js cleanup --keep-reports   # only delete crash files, preserve reports
node dist/cli.js cleanup --keep-manifests # preserve processed manifests

Fix Tracking

Crash fix statuses are stored in {CRASH_ANALYSIS_PARENT}/StateMaintenance/fix_status.json (local only, gitignored).

{
  "EXC_BAD_ACCESS||MyApp  -[ViewController load]||...": {
    "fixed": true,
    "note": "Fixed in PR #42",
    "updatedAt": "2026-03-22T16:00:00.000Z"
  }
}