Skip to main content
Glama

crash-mcp

CI License: MIT Python 3.10+

crash-mcp is an MCP server that inspects native crash dumps (ELF core and Windows minidump) and presents the crash reason, faulting thread, and stack trace to an AI assistant. It never executes the dump.

Turkish / Türkçe: crash-mcp, ELF core ve Windows minidump çökme dökümlerini inceleyen bir MCP sunucusudur. Çökme nedeni, hata veren iş parçacığı ve stack trace'i bir AI asistanına sunar. Döküm dosyasını asla çalıştırmadan, salt okunur analiz yapar.


Platform Support

Platform

ELF core (gdb)

Windows minidump

Notes

Linux

✅ Full

✅ Yes

gdb required for ELF core stack traces

Windows

⚠️ Summary only

✅ Full

gdb is not available; minidump is the primary path

macOS

⚠️ Summary only

✅ Yes

gdb may not be installed

On Windows, ELF core dumps can still be parsed for basic info (arch, threads, modules), but stack traces via gdb are unavailable. Windows minidump files are fully supported.


Related MCP server: MCP Server for WinDbg Crash Analysis

Install

From PyPI (when published)

pip install crash-mcp

From GitHub

pip install git+https://github.com/RivaExits0/crash-mcp.git

From Source

git clone https://github.com/RivaExits0/crash-mcp.git
cd crash-mcp
pip install -e .[dev]    # or just `pip install -e .` for production

System requirements (Linux): gcc, gdb, and binutils for building test fixture. Optional: install gdb for ELF core stack traces (Linux only).


Build the Test Fixture (Linux)

make

Compiles tests/crash and generates tests/core. Requires gcc and a kernel that allows core dumps. On Windows, skip this step; minidump tests use mocks.


Run

crash-mcp
# or
python -m crash_mcp

The server speaks MCP over stdio.


Claude Desktop Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "crash-mcp": {
      "command": "crash-mcp",
      "args": [],
      "env": {}
    }
  }
}

Windows: If installed via pip, crash-mcp should be on PATH. Otherwise use full path: C:\\path\\to\\crash-mcp\\.venv\\Scripts\\crash-mcp.exe.


OpenCode Integration

Add to opencode.json:

{
  "mcp": {
    "crash": {
      "type": "local",
      "command": ["crash-mcp"],
      "enabled": true
    }
  }
}

MCP Tools

Tool

Description

When to call

crash_load(dump_path, binary_paths=[], symbols_path=None)

Load a dump (ELF core or Windows minidump) and detect its format.

First, before any other crash_* tool.

crash_summary()

Crash type, faulting address, thread, arch, module, symbols.

After crash_load.

crash_threads(limit=20, offset=0)

List threads (paginated).

To find the faulting thread.

crash_stack(thread_id, limit=30, offset=0)

Stack frames for a thread.

After crash_threads, to inspect a thread.

crash_disassemble(address, before=8, after=8)

Disassemble around an address.

To inspect instructions near crash PC.

crash_compare(dump_path_a, dump_path_b)

Compare two dumps.

To check if two crashes are similar.


Tool: crash_load

Example call:

{"tool": "crash_load", "args": {"dump_path": "tests/core", "binary_paths": ["tests/crash"]}}

Example output:

{
  "format": "ELF core",
  "arch": "arm64",
  "os": "Linux/Unix",
  "process_name": "crash",
  "crash_thread": 4486,
  "crash_signal": "SIGSEGV",
  "signal_code": 1,
  "crash_pc": "0x4007c4",
  "crash_pc_str": "0x4007c4 (/path/to/tests/crash+0x7c4)",
  "thread_count": 1,
  "module_count": 3,
  "gdb_available": true
}

Tool: crash_summary

Example call:

{"tool": "crash_summary", "args": {}}

Example output:

{
  "format": "ELF core",
  "arch": "arm64",
  "crash_signal": "SIGSEGV",
  "crash_thread": 4486,
  "crash_pc": "0x4007c4",
  "process_name": "crash"
}

Tool: crash_threads

Example call:

{"tool": "crash_threads", "args": {"limit": 5, "offset": 0}}

Example output:

{
  "total": 1,
  "offset": 0,
  "limit": 5,
  "threads": [
    {
      "thread_id": 4486,
      "state": "crashed",
      "signal": 11,
      "pc": "0x4007c4",
      "pc_str": "0x4007c4 (/path/to/tests/crash+0x7c4)"
    }
  ]
}

Tool: crash_stack

Example call:

{"tool": "crash_stack", "args": {"thread_id": 4486, "limit": 10, "offset": 0}}

Example output:

{
  "thread_id": 4486,
  "source": "gdb",
  "total": 2,
  "offset": 0,
  "limit": 10,
  "frames": [
    {"index": 0, "text": "#0  0x00000000004007c4 in boom (x=42) at crash.c:6"},
    {"index": 1, "text": "#1  0x00000000004007e4 in main () at crash.c:10"}
  ],
  "gdb_error": null
}

Tool: crash_disassemble

Example call:

{"tool": "crash_disassemble", "args": {"address": "0x4007c4", "before": 2, "after": 2}}

Example output:

{
  "address": "0x4007c4",
  "address_str": "0x4007c4 (/path/to/tests/crash+0x7c4)",
  "before": 2,
  "after": 2,
  "instructions": [
    {"address": 0x4007c0, "mnemonic": "str", "op_str": "w1, [x8]", "bytes": "..."},
    {"address": 0x4007c4, "mnemonic": "ret", "op_str": "", "bytes": "..."}
  ]
}

Tool: crash_compare

Example call:

{"tool": "crash_compare", "args": {"dump_path_a": "tests/core", "dump_path_b": "tests/core"}}

Example output:

{
  "format_a": "elf_core",
  "format_b": "elf_core",
  "crash_signal_a": "SIGSEGV",
  "crash_signal_b": "SIGSEGV",
  "crash_pc_a": "0x4007c4",
  "crash_pc_b": "0x4007c4",
  "thread_count_a": 1,
  "thread_count_b": 1
}

Pagination (limit / offset)

crash_threads and crash_stack support limit and offset:

  • limit: maximum number of items to return (default 20 for threads, 30 for stack)

  • offset: number of items to skip (default 0)

Response includes a pagination-style object with total, offset, limit, returned, and has_more.


Testing

Linux (full suite)

make test

Runs the full pytest suite: ELF core integration (real core dump + gdb), minidump parser, MCP smoke test, error paths, pagination. 31 tests.

Windows (minidump only)

python -m pytest tests/test_minidump_mock.py tests/test_extra.py -q

Runs minidump mock tests and session/validation tests that do not require a core dump or gdb.

macOS (minidump only)

python -m pytest tests/test_minidump_mock.py tests/test_extra.py -q

Architecture

src/crash_mcp/
├── server.py           MCP tool definitions (stdio transport)
├── analyzer.py         Session management and common reporting
├── elf_core.py         ELF core parsing and gdb-based stack traces (Linux)
├── minidump_reader.py  Windows minidump parsing
└── platform_utils.py   Cross-platform paths, subprocess, file I/O

Security

  • No shell=True; external commands use argument lists with timeouts.

  • No dump execution, no network, no filesystem scanning beyond provided paths.

  • Sensitive memory is not returned by default; only registers, addresses, frames.


Limitations

  • ELF core stack traces require gdb (Linux only).

  • Minidump stack traces are best-effort frame-pointer walks.

  • Minidump thread context parsing depends on the minidump library version.

  • On Windows, ELF core stack traces are unavailable (no gdb).

  • Static analysis cannot guarantee runtime behaviour.


  • forge-mcp — Game modding toolkit (hex, PE, APK, Unity, Unreal, tables). Use for hex editing, signature generation, APK repacking.

  • emu-mcp — Isolated function emulation with Unicorn. Use for verifying function behavior with concrete inputs.

  • henry-mcp — Static compatibility analysis for EXE/DLL/APK/Kotlin. Use for checking module compatibility.


📦 Release

  • Latest: v0.1.0

  • Install from release: pip install git+https://github.com/RivaExits0/crash-mcp.git@v0.1.0

Create Release

git tag -a v0.1.0 -m "crash-mcp v0.1.0: Initial release"
git push origin v0.1.0

License

MIT — see LICENSE.

Available Tools

6 tools
crash_compareB

Compare two crash dumps.

Use to check whether two crashes have the same type/address/module/thread counts. Best-effort; missing symbols are reported.

Inputs: dump_path_a (required), dump_path_b (required). Returns: result

crash_disassembleA

Disassemble memory around an address in the dump.

Use to inspect instructions near the crash address. before/after are instruction counts (capped). Returns an error if memory is unavailable.

Inputs: address (required), after, before. Returns: result

crash_loadA

Load a crash dump (ELF core or Windows minidump) into the session.

Use first, before any other crash_* tool. Detects format, architecture, threads, modules and exception info. Does not execute the dump. Missing binaries/symbols are reported, not guessed.

Inputs: dump_path (required), binary_paths, symbols_path. Returns: result

crash_stackA

Return stack frames for a thread.

Use after crash_threads to inspect a specific thread. Shows symbols when available, otherwise module+RVA. Paginated by limit/offset. Reports the reason if unwinding is unavailable.

Inputs: thread_id (required), limit, offset. Returns: result

crash_summaryA

Return a short summary of the loaded dump.

Use to get crash type, faulting address, faulting thread, arch, module and symbol resolution status. Returns unknown for missing fields.

Inputs: no named parameters. Returns: result

crash_threadsA

List threads in the loaded dump.

Use to find the faulting thread or inspect thread states. Supports limit/offset pagination.

Inputs: limit, offset. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool maps to a distinct action in a clear pipeline: load the dump, summarize it, enumerate threads, unwind a stack, disassemble at an address, and compare two dumps. Descriptions explicitly sequence the tools (load first, stack after threads), so there is no realistic misselection between them.

    Naming Consistency5/5

    All six tools use the same crash_ prefix followed by a short lowercase noun/verb token (load, summary, threads, stack, disassemble, compare). The pattern is uniform and predictable, making the set easy to scan.

    Tool Count5/5

    Six tools is a tight, well-scoped surface for crash dump triage; every tool has a distinct job and none appear redundant. Nothing feels padded or arbitrarily split.

    Completeness4/5

    The core workflow (load → summary → threads → stack → disassemble → compare) is fully covered, including pagination and graceful error reporting. However, there is no register inspection, module listing, or memory/string search tool, which are common needs in crash analysis and would force workarounds.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers