whistle.agent-mcp

English

Let AI assistants that support MCP directly query the HTTP, HTTPS, and WebSocket traffic currently captured by Whistle.

You don't need to export sessions, copy response content, or manually organize request information. After connecting, you can directly let the AI search requests, view full sessions, and analyze WebSocket frames.

What it's good for

• Find requests that recently failed, timed out, or matched a specific URL.

• View the request headers, response headers, body, duration, and matching rules of a single request.

• Investigate WebSocket message content and send/receive direction.

• Let AI assist in analyzing network issues without modifying Whistle configuration or captured data.

Related MCP server: Android Proxy MCP

Quick start

Requirements: Node.js 20+, Whistle>=2.10.7.

On first use, copy and run all the commands below:

npm install -g whistle@latest
w2 install @wilson_janet/whistle.agent-mcp
w2 start

If Whistle is already running, just install the plugin and restart:

w2 install @wilson_janet/whistle.agent-mcp
w2 restart

Verify the plugin is available:

curl http://127.0.0.1:8899/whistle.agent-mcp/health

Add the following to your MCP client configuration file:

{
  "mcpServers": {
    "whistle": {
      "url": "http://127.0.0.1:8899/whistle.agent-mcp/mcp"
    }
  }
}

After connecting, you can directly ask questions like this:

查找最近 20 个状态码为 500 的请求。
查看 URL 包含 /api/orders 的最新请求，分析它为什么失败。
读取会话 1750000000000-001 的请求、响应和耗时。
查看指定 WebSocket 会话最近由服务端发送的消息。

Provided tools

Session IDs in search results can be passed on to the detail and frame query tools.

Security and limitations

• All tools are read-only; they do not modify rules, proxy settings, or captured data, and do not replay requests.

• Sensitive request headers such as authorization, cookie, API Key, and Token are automatically replaced with [REDACTED].

• Text bodies return at most 200,000 characters; binary content only returns a limited-length base64 preview.

• Data comes from Whistle's in-memory cache; older sessions may have already expired.

• By default, only localhost Origin is accepted. Do not expose the Whistle UI port to untrusted networks without authentication.

To add a Bearer Token for the MCP endpoint, set it when starting Whistle:

WHISTLE_MCP_TOKEN='your-token' w2 restart

Then configure the same Bearer Token for the service in the MCP client. You can also add additional exact Origins via WHISTLE_MCP_ALLOWED_ORIGINS, separating multiple values with commas.

Development

After entering the project directory, install dependencies and build:

npm install
npm run build

When loading a local plugin from source, -A must point to the parent directory containing whistle.agent-mcp:

w2 start -A ..

Start the TypeScript watcher, Whistle, and local plugin reload:

npm run dev

Full verification:

npm run check
npm test
npm run build
npm run smoke

npm run smoke:api additionally connects to the locally installed Whistle Local Agent API and uses the current captured data to verify query capabilities.

Project structure

index.cjs              Whistle 插件入口
src/
  plugin/handler.ts    HTTP 路由与访问控制
  mcp/server.ts        MCP 工具定义
  whistle/             API 适配、查询、脱敏、错误与类型
  testing/smoke.ts     构建后的端到端 smoke test
test/
  whistle/             Whistle 相关单元测试
scripts/dev.sh         本地开发脚本