IDA-MCP

IDA-MCP is an IDA Pro plugin that exposes IDA analysis, database modification, debugger, and lifecycle operations through MCP. Each IDA instance runs a local FastMCP HTTP server, and a standalone gateway provides a stable multi-instance MCP endpoint.

Layout

IDA-MCP/
├── ida_mcp.py          # IDA plugin entry point, exposes PLUGIN_ENTRY()
├── ida-plugin.json     # IDA plugin metadata
├── ida_mcp/            # plugin package, gateway, proxy, tools, resources
├── install.py          # interactive installer
├── test/               # live-IDA pytest suite
├── API.md              # MCP, tool, resource, and internal HTTP contract
├── project.md          # repository map and boundaries
├── roadmap.md          # current direction and milestones
└── requirements.txt    # IDA Python runtime dependencies

Related MCP server: PCM

Runtime Model

• IDA loads ida_mcp.py, which starts ida_mcp/plugin_runtime.py.

• Each IDA instance chooses a free port starting at ida_default_port and serves MCP at /mcp/.

• The standalone gateway listens on 127.0.0.1:11338, registers instances under /internal/*, and exposes the proxy MCP endpoint at /mcp.

• Tool registration is decorator based: use @tool plus @idaread or @idawrite.

• Loopback gateway requests (127.0.0.1 / ::1) do not require gateway_token; non-loopback requests require a matching token and fail closed when it is empty.

• py_eval, patch_bytes, apply_patch, and dbg_* tools are unsafe and gated by enable_unsafe=false by default in ida_mcp/config.conf.

Installation

Requirements:

• Python > 3.11

Install with HCLI

Install the packaged plugin archive attached to the latest GitHub Release:

hcli plugin install https://github.com/Captain-AI-Hub/IDA-MCP/releases/latest/download/main.zip

Alternatively, install from a local checkout with machine-aware path detection:

git clone https://github.com/Captain-AI-Hub/IDA-MCP.git
cd IDA-MCP
python scripts/package_hcli.py --output dist/main.zip
python scripts/hcli_install.py dist/main.zip

The wrapper asks for or detects the IDA executable, probes that installation's idat runtime, and falls back to parsing idapyswitch only when the runtime probe is unavailable. It then sets HCLI_CURRENT_IDA_PYTHON_EXE while launching HCLI, so dependency installation cannot fall back to HCLI's/system Python. The wrapper uses the detected interpreter internally; the direct HCLI install does not prompt for or overwrite ida_python:

IDAPython interpreter path (C:\Users\name\AppData\Local\Python\pythoncore-3.12-64\python.exe)

Specify IDA explicitly when automatic discovery selects the wrong installation:

python scripts/hcli_install.py dist/main.zip --ida D:\IDAPro9.4\ida.exe

On Linux, the wrapper also reads $IDAUSR/ida-config.json (default: ~/.idapro/ida-config.json) and searches common /opt, home, and local application paths. To use HCLI directly while forcing a known IDAPython interpreter, set the override explicitly:

HCLI_CURRENT_IDA_PYTHON_EXE=/path/to/idapython/bin/python3 \
  hcli plugin install https://github.com/Captain-AI-Hub/IDA-MCP/releases/latest/download/main.zip

If IDAPython cannot be detected, scripts/hcli_install.py stops instead of allowing dependency installation through the system Python. The wrapper also generates a per-install token and prints a copy/paste-ready mcp.json. This does not apply to the direct URL form: hcli plugin install ... does not execute IDA-MCP, so it cannot generate or print a machine-specific token during installation.

For plugin development, use hcli plugin install --editable . so source changes are picked up without reinstalling. HCLI installs the plugin files and Python runtime dependencies declared in ida-plugin.json. Dependency resolution can take a while on the first installation and may produce little output; wait for the final Installed plugin message.

Starting with v0.6.3, HCLI prompts for the IDA executable, IDAPython interpreter, automatic instance startup, gateway host/port/path, autonomous launch mode, unsafe-tool policy, request timeout, and debug logging. The IDAPython default remains auto, but the prompt is retained because detection can be wrong for non-standard IDA layouts. auto_start is also prompted and defaults to No. The hidden gateway lifecycle action defaults to idle, so a fresh installation performs no server startup unless requested.

Get the gateway token and configure an MCP client

hcli plugin install only installs the plugin metadata, files, and Python dependencies. It does not load IDA-MCP, so the install command cannot generate or print the machine-specific gateway token.

1. Generate the token on the first IDA launch

After installation:

1. Start IDA and open a database.

2. Wait for IDA-MCP to load.

3. On its first load, IDA-MCP generates a random gateway token and shows it in the IDA output window and, in interactive mode, a dialog.

4. Copy the displayed token and the generated MCP client configuration.

Retrieve a previously generated token with:

hcli plugin config IDA-MCP get gateway_token

If this command returns __AUTO_GENERATE_GATEWAY_TOKEN__, IDA-MCP has not completed first-launch initialization, or it could not write to the HCLI settings store. Start IDA and check the IDA output window. If IDA-MCP reports that it saved the token to ida_mcp/config.conf, use the token displayed in IDA or read it from that installed plugin configuration file.

To set your own token, use a random value of at least 20 characters:

hcli plugin config IDA-MCP set gateway_token YOUR_RANDOM_TOKEN

Do not commit a real gateway token to a repository or paste it into public logs.

2. Start IDA-MCP when automatic startup is disabled

auto_start defaults to No. Open the target database and run the IDA-MCP plugin once from IDA to start its instance server. Start the standalone gateway with:

hcli plugin config IDA-MCP set gateway start

To enable automatic instance startup later:

hcli plugin config IDA-MCP set auto_start true

The default gateway MCP endpoint is:

http://127.0.0.1:11338/mcp

If you changed http_host, http_port, or http_path during installation, use those values instead.

3. Claude Code and Cursor mcpServers format

Claude Code project configuration uses .mcp.json in the project root. Cursor uses .cursor/mcp.json for a project or ~/.cursor/mcp.json globally. These clients use the common top-level mcpServers object:

{
  "mcpServers": {
    "ida-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:11338/mcp",
      "headers": {
        "Authorization": "Bearer REPLACE_WITH_GATEWAY_TOKEN"
      }
    }
  }
}

IDA-MCP also accepts the following header as an alternative:

{
  "X-IDA-MCP-Token": "REPLACE_WITH_GATEWAY_TOKEN"
}

Use one authentication header; Authorization: Bearer ... is recommended for normal HTTP MCP clients.

For Claude Code, avoid storing the token directly in a project .mcp.json by using an environment variable. Claude Code expands ${VAR} in HTTP URLs and headers:

export IDA_MCP_TOKEN='YOUR_GATEWAY_TOKEN'

{
  "mcpServers": {
    "ida-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:11338/mcp",
      "headers": {
        "Authorization": "Bearer ${IDA_MCP_TOKEN}"
      }
    }
  }
}

The equivalent Claude Code CLI command is:

claude mcp add --transport http ida-mcp http://127.0.0.1:11338/mcp \
  --header "Authorization: Bearer $IDA_MCP_TOKEN"

For Cursor, if environment-variable interpolation is unavailable in the client version being used, place the literal token only in the personal global file ~/.cursor/mcp.json; do not commit that file.

4. VS Code .vscode/mcp.json format

VS Code uses a top-level servers object rather than mcpServers. The example below prompts for the token and stores it in VS Code's input/secret flow instead of committing it to the workspace file:

{
  "inputs": [
    {
      "id": "ida-mcp-token",
      "type": "promptString",
      "description": "IDA-MCP gateway token",
      "password": true
    }
  ],
  "servers": {
    "ida-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:11338/mcp",
      "headers": {
        "Authorization": "Bearer ${input:ida-mcp-token}"
      }
    }
  }
}

5. Reset first-launch values

To generate a new token and retry IDAPython detection:

hcli plugin config IDA-MCP del gateway_token
hcli plugin config IDA-MCP set ida_python auto

Restart IDA afterward. IDA-MCP displays the new token, effective gateway URL, detected IDAPython executable, and a copy/paste-ready MCP configuration.

GitHub's automatically generated archive/refs/heads/main.zip source archive is not an HCLI single-plugin archive. Use the Release asset above or build the correct archive locally:

python scripts/package_hcli.py --output dist/main.zip
hcli plugin lint dist/main.zip
python scripts/hcli_install.py dist/main.zip

Install with the interactive installer

Run the interactive installer from the repository root:

python install.py

The installer performs the full setup flow:

1. Locate the IDA installation directory.

2. Locate the IDAPython interpreter used by that IDA installation.

3. Optionally install requirements.txt into IDA's Python environment.

4. Copy ida_mcp.py, ida-plugin.json, and the ida_mcp/ package into IDA's plugins/ directory.

5. Review and write ida_mcp/config.conf, including an auto-generated gateway token.

For manual installation, copy ida_mcp.py, ida-plugin.json, and the ida_mcp/ directory into IDA's plugin directory, then install dependencies into IDA's Python environment:

<ida_python> -m pip install -r requirements.txt

Open a database in IDA and wait for initial analysis. If auto_start is false, run the IDA-MCP plugin once from IDA; otherwise its per-instance MCP server starts automatically.

HCLI Packaging

.github/workflows/package-hcli.yml builds dist/main.zip on every push to main, on published Releases, and on manual dispatch. Every run uploads the ZIP as an Actions artifact. Release-triggered runs also attach main.zip to that Release.

To attach the package to a Release such as v0.6.3, push the workflow first and run the command below. If that Release does not exist, the workflow creates it at the dispatched commit before uploading main.zip:

gh workflow run package-hcli.yml -f release_tag=v0.6.3

The archive deliberately places ida-plugin.json at the ZIP root, which is the layout required for HCLI URL installation.

Gateway Control Through HCLI

Gateway lifecycle actions use HCLI's existing cross-platform plugin config command, so no .cmd, shell script, PATH modification, or HCLI extension is required:

hcli plugin config IDA-MCP set gateway start
hcli plugin config IDA-MCP set gateway stop
hcli plugin config IDA-MCP set gateway restart

The gateway setting defaults to idle, so a fresh installation does not start the standalone gateway automatically. IDA-MCP resets explicit start, stop, or restart requests to idle before executing them. The command is consumed by a lightweight watcher in the IDA plugin. If IDA is not currently running, the action remains stored and is executed the next time IDA-MCP loads. Start and restart use the configured request_timeout.

The standalone command.py remains available for complete lifecycle, instance, tool, and resource operations:

python ida_mcp/command.py gateway status
python ida_mcp/command.py ida list
python ida_mcp/command.py tool call get_metadata --port 10000

Default endpoints:

• Gateway MCP proxy: http://127.0.0.1:11338/mcp

• Gateway internal API: http://127.0.0.1:11338/internal/*

• Direct IDA instance MCP: http://127.0.0.1:<instance_port>/mcp/

Tests

Tests require a running gateway and at least one registered IDA instance.

python test/test.py
python test/test.py --core --analysis

pytest -m "core or analysis"
pytest -m "not debug"

The debug marker is excluded by default because it requires an active debugger. API call logs are written to .artifacts/api_logs/.

Documentation

• API.md documents the MCP tools, resources, proxy behavior, and internal HTTP routes.

• project.md explains repository responsibilities and module boundaries.

• roadmap.md tracks current stabilization work.