headless-ida

This MCP server provides a headless analysis workflow using IDA Pro's headless mode. It exposes a set of MCP tools to manage and manipulate functions, variables, and other binary artifacts through a lightweight server you can connect to with MCP clients. To run, start the server via UV (Python) using the included headless_ida_mcp_server entry point. Once up, you can connect with an MCP client to issue commands and workflows that leverage IDA's headless analysis capabilities. The server supports inspecting and annotating binary data, running analysis passes, and applying transformations or extractions that are exposed through the MCP API. The example client command demonstrates starting an inspector client to debug or interact with the server, enabling you to explore the available MCP endpoints and operations.

Prerequisites:

• Python 3.12 or higher
• IDA Pro with headless support (idat)

Installation steps:

1. Clone the project locally: git clone https://github.com/cnitlrt/headless-ida-mcp-server.git cd headless-ida-mcp-server

2. Install dependencies using UV (Python) environment: uv python install 3.12 uv venv --python 3.12 uv pip install -e .

3. Prepare environment configuration:

   • Copy the example environment file: cp .env_example .env
   • Edit .env to set: IDA_PATH: Path to IDA Pro's headless executable (idat) PORT: MCP server port (e.g., 8888) HOST: MCP server host (e.g., 127.0.0.1) TRANSPORT: MCP transport mode (sse or stdio)

4. Run the server via UV: uv run headless_ida_mcp_server

Environment variables:

• IDA_PATH must point to your IDA Pro headless binary (idat).
• PORT/HOST determine how clients connect to the MCP server.
• TRANSPORT should be sse for server-sent events or stdio for standard I/O based communication. If you encounter issues launching, verify that the IDA headless executable is accessible and that the port is free. When running behind a firewall or in containerized environments, ensure the HOST/PORT settings permit inbound connections. The MCP endpoints offered by this server are designed to coordinate with the headless-ida tooling exposed via MCP; consult the client tools to discover available commands and data structures.