angr-mcp MCP Server

This project implements a Model Context Protocol (MCP) server that exposes core angr binary-analysis capabilities—loading binaries, constructing symbolic states, steering execution, and harvesting exploit artifacts—through a set of tool handlers. The initial focus is rapid vulnerability exploration: analysts can load a target, make its inputs symbolic, drive execution toward interesting addresses, and extract concrete witness inputs once a path of interest is found.

Current Components

• angr_mcp/registry.py – In-memory registry tracking angr projects, states, simulation managers, hooks, cached analyses, alert logs, and persisted job metadata.
• angr_mcp/server.py – The MCP server entry point. It implements handlers for project loading, symbolic-state creation, environment instrumentation (hooks and SimProcedures), symbolic execution, breakpoint-style monitoring, state inspection, structured alert reporting, job persistence/management, constraint solving, CFG recovery, and backward slicing. It also integrates community exploration techniques shipped in awesome-angr/ExplorationTechniques.
• angr_mcp/utils/ – Binary-inspection and state-mutation helpers shared by the MCP handlers and tests (section scanners, literal cross-referencing, register/stack mutation primitives, and symbolic-handle registration).
• tests/test_mcp_server.py – Integration tests that compile a small C binary and exercise the server end-to-end (load project, set symbolic stdin, run a targeted search, solve constraints, capture monitored events, and perform CFG/slice queries).
• tests/test_phase1_ctf.py – Phase 1 regression suite recreating angr CTF levels 00–04 exclusively through MCP handlers, asserting predicate metadata, register/stack mutation APIs, and native replay of recovered inputs.
• tests/test_deep_call_partition.py – Deep-call regression that builds a branching binary, extracts call chains, enforces state-budget guards, and demonstrates chunked symbolic execution reaching a buried target function.
• tests/test_taint_analysis.py – Format-string taint regression that exercises pointer-aware taint sources and verifies sinks triggered through the new taint-analysis MCP handler.
• pyproject.toml – Minimal configuration enabling uv to manage a local virtual environment.
• schemas/ – JSON Schema Draft 2020-12 definitions for every MCP handler request/response pair plus shared structures (alerts, jobs, UUIDs).

Environment Setup

1. Create and activate the virtual environment with uv:

   UV_CACHE_DIR=.uv-cache uv venv .venv
   source .venv/bin/activate
   

2. Install dependencies into the environment (angr and claripy are pulled from PyPI):

   UV_CACHE_DIR=.uv-cache uv pip install --python .venv/bin/python claripy angr
   

3. Run the integration tests:

   .venv/bin/python -m unittest discover tests