maglu/mcp-crash-analyzer

MCP Crash Analyzer

A Model Context Protocol (MCP) server for automated crash analysis using GDB.

Introduction

This MCP tool analyzes program crashes and provides detailed debugging insights, including register states, memory snapshots, disassembly, and stack traces.

It was created as a learning exercise to explore how the Model Context Protocol (MCP) works and was built largely with the help of AI agents. The tool has been tested on a few specific crash scenarios and produced promising results, though it hasn’t been deeply validated on more complex cases.

I don’t plan to continue active development, but if you encounter issues or have interesting feature ideas, feel free to open a ticket in the Issues tab — if time allows, I’ll take a look. Contributions, feedback, or forks are always welcome.

Features

🔍 Automatic Crash Detection - Runs programs and detects crashes automatically
📊 Comprehensive Analysis - Captures signal, location, backtrace, registers, memory
🎯 Smart Disassembly - Full function disassembly with crash location marking
💾 Memory Inspection - Read memory at any address with hex/ASCII formatting
⚙️ Register State - Complete CPU register snapshot at crash time
🏗️ System Info - Architecture, debug symbols, endianness detection
⚡ Session-Based - Load once, query multiple times for detailed analysis

Quick Start

Installation

# Install dependencies
pip install -r requirements.txt

Configuration

Add to your MCP settings file:

VS Code with Cline (~/.config/Code/User/mcp.json):

{
  "mcpServers": {
    "crash-analyzer": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp_crash_analyzer.py"]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "crash-analyzer": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp_crash_analyzer.py"]
    }
  }
}

Environment Variables

• MCP_CRASH_ANALYZER_LOG - Custom log file path (optional)
  • Default: ~/.cache/mcp_crash_analyzer.log
  • Example: export MCP_CRASH_ANALYZER_LOG=/var/log/crash_analyzer.log

Usage

Basic Workflow

1. Load and run a program until it crashes:

load_and_run("/path/to/program", args=["arg1"], timeout=10)

2. Analyze the crash:

get_disassembly_function()  # See crash instruction
get_registers()             # Check CPU state
read_memory("$rsp", 64)     # Inspect memory

3. Close when done:

close_session()

Available Tools

Core Tools

• load_and_run(binary_path, args=None, timeout=10)
  Load and run program until crash or exit

• get_registers(register_names=None)
  Get CPU register values at crash time

• get_disassembly_function()
  Get complete disassembly of crash function

• get_disassembly_range(start_address, end_address, mode=0)
  Disassemble specific address range

• read_memory(address, size, format="hex")
  Read memory at any address

• get_system_info()
  Get architecture and debug info

• get_full_report()
  Get complete crash report

• close_session()
  Close GDB session

Example Analysis

# 1. Run program
result = load_and_run("/path/to/crashed_program")
# {"crashed": true, "signal": "SIGSEGV", ...}

# 2. See where it crashed
disasm = get_disassembly_function()
# "0x12345: mov (%rax),%ebx ← CRASH"

# 3. Check registers
regs = get_registers(["rax", "rbx", "rsp"])
# {"rax": "0x0", "rbx": "0x7fff...", ...}

# 4. Read stack
mem = read_memory("$rsp", 128, "both")

# 5. Close
close_session()

Example Output

{
  "crashed": true,
  "signal": {
    "name": "SIGSEGV",
    "meaning": "Segmentation fault"
  },
  "location": {
    "function": "process_data",
    "address": "0x555555555234",
    "file": "main.c",
    "line": "42"
  },
  "disassembly": [
    "0x555555555230: mov    %rdi,%rax",
    "0x555555555234: mov    (%rax),%edx ← CRASH",
    "0x555555555236: add    $0x1,%edx"
  ]
}

Common Signal Types

When analyzing crashes, you'll encounter these common signals:

• SIGSEGV - Segmentation fault (invalid memory access, NULL pointer dereference)
• SIGABRT - Abort signal (assertion failure, abort() call)
• SIGFPE - Floating point exception (division by zero, invalid math operation)
• SIGILL - Illegal instruction (corrupted code, wrong architecture)
• SIGBUS - Bus error (misaligned memory access)
• SIGSYS - Bad system call

Requirements

• Python 3.8+
• GDB (GNU Debugger)
• pygdbmi - Python GDB Machine Interface
• fastmcp - Fast MCP server framework

Use Cases

• Automated Testing: Detect and analyze crashes in CI/CD pipelines
• Bug Triage: Generate detailed crash reports with full context
• Forensics: Post-mortem debugging of production crashes
• Security Analysis: Analyze exploits and vulnerabilities
• Learning: Study assembly, understand why programs crash
• Development: Quick crash analysis without manual GDB sessions

Crash Analysis Workflow

The crash analyzer provides detailed information about program failures:

What Gets Captured

1. Signal Information - Type of crash and what caused it
2. Crash Location - Exact function, file, line, and address
3. Backtrace - Full call stack showing how program reached the crash
4. Register Values - CPU state at crash time (for low-level debugging)
5. Local Variables - Variable values in the crashing function
6. Disassembly - Assembly instructions around crash address
7. Memory State - Stack and heap inspection
8. Console Output - All program output before the crash

Analysis Modes

Session-Based (Advanced):

• Load program once with load_and_run()
• Query details with individual tools
• Fine-grained control over what to inspect
• Best for deep debugging

Full Report (Quick):

• Get everything at once with get_full_report()
• Complete crash analysis in one call
• Best for automated reporting

How It Works

1. Uses pygdbmi to control GDB via Machine Interface
2. Maintains session state between load and analysis
3. Captures register snapshot at crash moment
4. Provides multiple analysis views (disassembly, memory, registers)

Limitations

• Platform: Linux/Unix only (requires GDB)
• Execution: Programs must be executable with proper permissions
• Reproducibility: Crashes must be reproducible (deterministic)
• Debug Info: Source line information requires debug symbols (-g flag)
• Core Dumps: Cannot directly analyze core dumps (run program instead)
• Single Crash: Analyzes first crash only (doesn't continue after crash)
• Optimization: Heavily optimized code may have incomplete variable information

Best Practices

1. Compile with debug symbols: Use -g flag for source line information
2. Disable optimization during debugging: Use -O0 to preserve variable info
3. Set appropriate timeouts: Increase timeout for slow-starting programs
4. Check permissions: Ensure binary has execute permissions (chmod +x)
5. Use absolute paths: Provide full paths to binaries and source files

🐛 Troubleshooting

📚 Resources

• pygdbmi: https://github.com/cs01/pygdbmi
• GDB/MI: https://sourceware.org/gdb/onlinedocs/gdb/GDB_002fMI.html
• MCP: https://modelcontextprotocol.io/

License

MIT License - Free to use and modify

Author

Magnus Lucchese

Note: This tool automates GDB for crash analysis. For interactive debugging, use GDB directly.