# AI-x64dbg-MCP

[English](#english) | [中文](#中文)

---

## English

x64dbg plugin that provides MCP (Model Context Protocol) interface for AI assistants.

### Features

- **MCP Protocol Support**: Exposes x64dbg debugging capabilities via JSON-RPC 2.0 over HTTP
- **Multi-Instance Support**: Automatically coordinates multiple x64dbg instances (x32/x64) through a single router port
- **Comprehensive Tool Set**: 12 tool categories covering all major debugging operations

#### Supported Tools

| Category | Description |
|----------|-------------|
| Breakpoint | Set, remove, enable/disable breakpoints |
| Execution | Run, step into, step over, pause, stop |
| Register | Read/write CPU registers |
| Memory | Read/write memory, allocate, protect |
| Disasm | Disassemble instructions at address |
| Symbol | Resolve symbols, get module info |
| Search | Pattern search in memory |
| Trace | Instruction tracing |
| Patch | Patch bytes/instructions in memory |
| Script | Execute x64dbg commands |
| Stack | Stack frame analysis |
| Process | Process and thread information |

### Installation

1. Download from [Releases](https://github.com/HyperClockUp/AI-x64dbg-MCP/releases)
2. Copy the plugins to x64dbg plugins folder:
   - `x64dbg_mcp.dp64` → `x64dbg/x64/plugins/`
   - `x32dbg_mcp.dp32` → `x64dbg/x32/plugins/`
3. Restart x64dbg

### Usage

#### MCP Endpoint

The plugin starts an HTTP server on port `13333` (configurable via `X64DBG_MCP_PORT` environment variable).

```
POST http://127.0.0.1:13333/mcp
Content-Type: application/json
```

#### Example Request

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
```


#### Multi-Instance Mode

When multiple x64dbg instances are running:
- First instance becomes **MASTER** and hosts the router
- Additional instances register as **SLAVE**
- All requests go through the master's router port
- Use `client_id` parameter to target specific instance

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "client_id": "client_2",
    "name": "get_registers",
    "arguments": {}
  }
}
```

### Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `X64DBG_MCP_PORT` | `13333` | Router port for MCP requests |

### MCP Client Configuration

#### Claude Desktop / Cursor / Kiro

```json
{
  "mcpServers": {
    "x64dbg": {
      "url": "http://127.0.0.1:13333/mcp"
    }
  }
}
```

---

## 中文

为 x64dbg 提供 MCP (Model Context Protocol) 接口的插件，让 AI 助手可以直接控制调试器。

### 功能特性

- **MCP 协议支持**：通过 HTTP JSON-RPC 2.0 暴露 x64dbg 调试功能
- **多实例支持**：自动协调多个 x64dbg 实例（x32/x64），通过单一路由端口访问
- **完整工具集**：12 个工具类别，覆盖所有主要调试操作

#### 支持的工具

| 类别 | 描述 |
|------|------|
| Breakpoint | 设置、删除、启用/禁用断点 |
| Execution | 运行、单步步入、单步步过、暂停、停止 |
| Register | 读写 CPU 寄存器 |
| Memory | 读写内存、分配、保护 |
| Disasm | 反汇编指定地址的指令 |
| Symbol | 解析符号、获取模块信息 |
| Search | 内存模式搜索 |
| Trace | 指令追踪 |
| Patch | 修补内存中的字节/指令 |
| Script | 执行 x64dbg 命令 |
| Stack | 栈帧分析 |
| Process | 进程和线程信息 |


### 安装方法

1. 从 [Releases](https://github.com/HyperClockUp/AI-x64dbg-MCP/releases) 下载插件
2. 复制插件文件到 x64dbg 插件目录：
   - `x64dbg_mcp.dp64` → `x64dbg/x64/plugins/`
   - `x32dbg_mcp.dp32` → `x64dbg/x32/plugins/`
3. 重启 x64dbg

### 使用方法

#### MCP 端点

插件会在端口 `13333` 启动 HTTP 服务器（可通过 `X64DBG_MCP_PORT` 环境变量配置）。

```
POST http://127.0.0.1:13333/mcp
Content-Type: application/json
```

#### 请求示例

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
```

#### 多实例模式

当运行多个 x64dbg 实例时：
- 第一个实例成为 **MASTER**，托管路由器
- 后续实例注册为 **SLAVE**
- 所有请求通过 master 的路由端口
- 使用 `client_id` 参数指定目标实例

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "client_id": "client_2",
    "name": "get_registers",
    "arguments": {}
  }
}
```

### 配置

| 环境变量 | 默认值 | 描述 |
|----------|--------|------|
| `X64DBG_MCP_PORT` | `13333` | MCP 请求的路由端口 |

### MCP 客户端配置

#### Claude Desktop / Cursor / Kiro

```json
{
  "mcpServers": {
    "x64dbg": {
      "url": "http://127.0.0.1:13333/mcp"
    }
  }
}
```

---

## License

Proprietary - Binary distribution only.

## Author

[HyperClockUp](https://github.com/HyperClockUp)