# idapin-mcp

Windows pipeline that compiles IDA’s **idadbg** PIN tool, wires it to **IDA Pro**, and exposes the same pintool to **any MCP-capable AI** (Grok, Claude Desktop, Cursor, VS Code, …) **without opening the IDA GUI**.

This repository includes **full project source**: the Windows pintool (`pintool/`), the MCP server (`src/idapin_mcp/`), and the install/build pipeline (`scripts/`).

PIN instruments a live process. `idadbg` speaks the IDA pintool protocol (v9). The MCP process is a TCP client for that protocol, so AI tools do not need the IDA GUI.

Intel PIN (`pin.exe`) is **not** vendored here (Intel license). `scripts/setup.ps1` downloads the PIN 3.31 MSVC kit.

## What you get

| Path | Role |
| --- | --- |
| `pintool/` | `idadbg.cpp` / headers / `.sln` — compile to `idadbg.dll` + `idadbg64.dll` |
| `src/idapin_mcp/` | MCP stdio server (`pin_launch`, `pin_read_regs`, …) |
| `scripts/setup.ps1` | Download PIN → build pintools → patch IDA `dbg_pin.cfg` → write MCP configs |
| `configs/` | Example IDA + MCP snippets |

```
AI client  --stdio MCP-->  python -m idapin_mcp  --TCP-->  pin.exe + idadbg*.dll  --instrument-->  target.exe
IDA Pro    --dbg_pin.cfg--> pin.exe + same DLLs   (optional GUI tracer)
```

## Requirements (Windows)

- Windows 10/11 x64
- Python 3.10+
- Visual Studio 2017 or newer **with MSVC x86/x64** (2019, 2022, 2026 all work; the build script picks the newest toolset)
- Windows 10 SDK (any 10.0.* installed with VS)
- IDA Pro 7.x/8.x/9.x **optional**, only if you also want the GUI PIN tracer
- Network once, to fetch Intel PIN 3.31 (`pin-external-3.31-98869-…-msvc-windows.zip`)

Admin is **not** required if you cannot write `C:\pin` — set `-PinRoot "$env:LOCALAPPDATA\idapin-mcp\pin"` (paths without spaces are safer for PIN).

## One-command setup

In **PowerShell** from the repo root:

```powershell
Set-ExecutionPolicy -Scope Process Bypass
.\scripts\setup.ps1
```

That will:

1. Create `%LOCALAPPDATA%\idapin-mcp\venv` and `pip install -e .`
2. Download PIN 3.31 into `C:\pin` (or the path you pass)
3. Copy `pintool/` into `PIN\source\tools\idapin`, retarget the VS project, build **Win32 + x64 Release**
4. Patch `dbg_pin.cfg` in every IDA install it finds
5. Register the MCP server in Grok, Claude Desktop, Cursor, and VS Code user configs

Then **restart the AI client**.

Custom PIN location:

```powershell
.\scripts\setup.ps1 -PinRoot "$env:LOCALAPPDATA\idapin-mcp\pin"
```

Step-by-step instead of the umbrella script: [docs/windows-build.md](docs/windows-build.md).

## MCP tools (for any AI)

After launch the process is **suspended** at `PROCESS_STARTED`. Set breakpoints, then resume.

| Tool | Purpose |
| --- | --- |
| `pin_launch` | Start PIN + pintool on a Windows EXE |
| `pin_status` / `pin_events` | Session and debug events |
| `pin_add_bpt` / `pin_del_bpt` | Software breakpoints |
| `pin_read_regs` / `pin_read_mem` / `pin_write_mem` | Registers / memory |
| `pin_resume` / `pin_pause` / `pin_step` | Control |
| `pin_meminfo` | Mapped sections |
| `pin_set_trace` / `pin_trace_count` | Instruction tracing |
| `pin_stop` | Kill the PIN process tree |

Example prompt:

> Use idapin MCP: `pin_launch` on `C:\Windows\System32\cmd.exe` with args `/c echo hi`, read registers, then `pin_resume` and `pin_stop`.

Manual MCP snippet: [configs/mcp.example.json](configs/mcp.example.json). Client-specific notes: [docs/ai-clients.md](docs/ai-clients.md).

## IDA Pro (GUI tracer)

`setup.ps1` writes:

```
PIN_PATH = "C:\\pin\\pin.exe";
PIN_TOOL_PATH = "C:\\pin\\source\\tools\\idapin";
PIN_TOOL_OPTIONS = 1
```

In IDA: **Debugger → Select debugger → PIN tracer**, then F9. Details: [docs/ai-clients.md](docs/ai-clients.md#ida-pro).

Headless **idalib** cannot start `pin_user.dll`; that is why this MCP talks to the pintool **directly**.

## License

Split licensing. The MCP server is MIT; the pintool is not.

| Tree | License / copyright |
| --- | --- |
| `src/idapin_mcp/`, `scripts/`, `configs/`, `docs/`, this README | **MIT** — [LICENSE](LICENSE) |
| `pintool/` | **Hex-Rays** copyright 2014–2019 — [pintool/COPYRIGHT](pintool/COPYRIGHT). Not MIT. Kept in source form because Intel forbids redistributing compiled PIN tools. |
| Intel PIN kit (`pin.exe`, headers, libs) | **Intel**. Not in this repo. Download separately and accept Intel’s license. |

See [NOTICE](NOTICE). Do not relicense `pintool/` as MIT.

Do not commit `pin.exe`, the PIN zip, or compiled `*.dll`.

Publish to GitHub from a browser (no Git install): [docs/publish-github.md](docs/publish-github.md).