Skip to main content
Glama
whistle-mcp

whistle-mcp

by hzbhzb

whistle-mcp

MCP (Model Context Protocol) Server for whistle - 让 AI 直接操作 whistle 的 Mock 数据。

安装

# 全局安装(推荐)
npm install -g whistle-mcp

# 或直接用 npx,无需安装
npx whistle-mcp

Related MCP server: SpyNet

配置

方式一:Cursor

编辑 Cursor 的 MCP 配置文件(~/.cursor/mcp.json):

{
  "mcpServers": {
    "whistle": {
      "command": "npx",
      "args": ["-y", "whistle-mcp"],
      "env": {
        "WHISTLE_BASE_URL": "http://127.0.0.1:8899",
        "WHISTLE_USERNAME": "",
        "WHISTLE_PASSWORD": ""
      }
    }
  }
}

全局安装后也可以写成:

{
  "mcpServers": {
    "whistle": {
      "command": "whistle-mcp",
      "env": {
        "WHISTLE_BASE_URL": "http://127.0.0.1:8899"
      }
    }
  }
}

方式二:Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "whistle": {
      "command": "npx",
      "args": ["-y", "whistle-mcp"],
      "env": {
        "WHISTLE_BASE_URL": "http://127.0.0.1:8899",
        "WHISTLE_USERNAME": "",
        "WHISTLE_PASSWORD": ""
      }
    }
  }
}

如果 whistle 启用了鉴权(w2 start -u admin -p 123456),请填写 WHISTLE_USERNAME 和 WHISTLE_PASSWORD。

方式三:其他 MCP 客户端

任何支持 stdio 传输的 MCP 客户端都可以使用:

WHISTLE_BASE_URL=http://127.0.0.1:8899 \
WHISTLE_USERNAME=admin \
WHISTLE_PASSWORD=123456 \
npx -y whistle-mcp

功能

规则管理

  • whistle_rule_list - 获取所有规则列表

  • whistle_rule_get - 获取规则内容

  • whistle_rule_set - 创建/更新规则

  • whistle_rule_remove - 删除规则

  • whistle_rule_enable / whistle_rule_disable - 启用/禁用规则

Values 管理

  • whistle_value_list - 获取所有 Values

  • whistle_value_get - 获取 Value 内容

  • whistle_value_set - 创建/更新 Value

  • whistle_value_remove - 删除 Value

Mock 工作流

  • whistle_mock_create - 一键创建完整 Mock 方案(规则 + Values)

  • whistle_mock_apply - 启用/禁用 Mock 规则

抓包数据查看

  • whistle_sessions_list - 获取最近抓包的 session 列表,可按 URL / HTTP 方法过滤

  • whistle_session_get - 获取单个请求的完整详情,自动解析 Query 参数、POST 参数和响应 JSON 字段树

  • whistle_sessions_search - 按请求参数名(query/POST body)或响应 JSON 字段名搜索抓包,例如"哪些请求带了 token 参数"、"哪些接口返回了 address 字段"

系统状态

  • whistle_status - 检查 whistle 服务状态

  • whistle_server_info - 获取服务器信息

环境变量

变量

默认值

说明

WHISTLE_BASE_URL

自动探测

whistle Web UI 地址。不设置时会自动读取 ~/.startingAppData/ 状态文件探测运行中的实例

WHISTLE_USERNAME

``

whistle 鉴权用户名(可选)

WHISTLE_PASSWORD

``

whistle 鉴权密码(可选)

端口自动探测

MCP Server 启动时会自动检测运行中的 whistle 实例(不管用什么端口启动),优先级:

  1. 环境变量 WHISTLE_BASE_URL(显式指定,最高优先级)

  2. whistle 状态文件 ~/.startingAppData/(自动探测)

  3. 默认 http://127.0.0.1:8899(fallback)

所以即使你 w2 start -p 8888 用别的端口启动,也能自动识别,无需改配置。

使用示例

1. 创建 Mock 接口

AI 指令:

帮我创建一个 Mock,当请求 api.example.com/user/info 时返回用户数据

AI 会调用:

{
  "tool": "whistle_mock_create",
  "arguments": {
    "pattern": "api.example.com/user/info",
    "response": {
      "code": 200,
      "data": {
        "id": 12345,
        "name": "张三",
        "email": "zhangsan@example.com"
      }
    },
    "statusCode": 200,
    "delay": 100
  }
}

2. 管理规则

AI 指令:

列出所有 whistle 规则

AI 会调用:

{
  "tool": "whistle_rule_list"
}

3. 更新 Mock 数据

AI 指令:

把用户 Mock 数据里的邮箱改成 lisi@example.com

AI 会调用:

{
  "tool": "whistle_value_set",
  "arguments": {
    "name": "mock_value_1234567890",
    "content": "{\"statusCode\":200,\"headers\":{\"Content-Type\":\"application/json\"},\"body\":{\"code\":200,\"data\":{\"id\":12345,\"name\":\"张三\",\"email\":\"lisi@example.com\"}}}"
  }
}

4. 查看抓包数据

AI 指令:

帮我看看最近有没有抓到 api.vip.com 的请求

AI 会调用:

{
  "tool": "whistle_sessions_list",
  "arguments": {
    "urlFilter": "api.vip.com",
    "count": 10
  }
}

AI 指令:

查看最后一个请求的完整响应数据

AI 会调用:

{
  "tool": "whistle_session_get",
  "arguments": {
    "id": "abc123-def456"
  }
}

5. 按参数/字段搜索抓包

AI 指令:

查一下最近有没有请求带了 userId 参数

AI 会调用:

{
  "tool": "whistle_sessions_search",
  "arguments": {
    "param": "userId",
    "count": 50
  }
}

AI 指令:

看看最近 POST 到 api.vip.com 的接口,返回的数据里有没有 address 字段

AI 会调用:

{
  "tool": "whistle_sessions_search",
  "arguments": {
    "urlFilter": "api.vip.com",
    "method": "POST",
    "field": "address",
    "count": 50
  }
}

前置条件

  1. whistle 已安装并运行:

    npm i -g whistle
    w2 start
  2. 确认 whistle Web UI 可访问:

    curl http://127.0.0.1:8899/cgi-bin/status

架构

┌─────────────┐      MCP (stdio)      ┌──────────────────┐      HTTP       ┌─────────────┐
│   AI Client │ ◄──────────────────► │ whistle-mcp-server│ ◄─────────────► │   whistle   │
│ (Claude/    │                      │   (Node.js)       │                 │  (127.0.0.1 │
│  Cursor)    │                      │                   │                 │   :8899)    │
└─────────────┘                      └──────────────────┘                 └─────────────┘
                                                                              │
                                                                              ▼
                                                                       ┌─────────────┐
                                                                       │ ~/.whistle/ │
                                                                       │  rules/     │
                                                                       │  values/    │
                                                                       └─────────────┘

开发

本地测试

# 启动 whistle
w2 start

# 启动 MCP Server(开发模式)
npm run dev

# 测试 MCP 协议
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node src/index.js

调试

查看 whistle Web UI 的 CGI 接口:

# 规则列表
curl http://127.0.0.1:8899/cgi-bin/rules/list

# Values 列表
curl http://127.0.0.1:8899/cgi-bin/values/list

License

MIT

Available Tools

17 tools
whistle_mock_applyC

启用或禁用指定的 Mock 规则

Inputs: ruleName (required), enable.

whistle_mock_createA

一键创建完整 Mock 方案:自动生成 Value(存储响应数据)+ 规则(匹配 URL),并立即启用

Inputs: pattern (required), response (required), delay, headers, +2 more.

whistle_rule_disableB

禁用指定规则

Inputs: name (required).

whistle_rule_enableB

启用指定规则

Inputs: name (required).

whistle_rule_getB

获取指定规则的详细内容

Inputs: name (required).

whistle_rule_listA

获取 whistle 中所有规则列表

Inputs: no named parameters.

whistle_rule_removeC

删除指定规则

Inputs: name (required).

whistle_rule_setB

创建或更新规则。规则内容使用 whistle 规则语法,如:pattern resBody://{valueName}

Inputs: name (required), content (required), enable.

whistle_server_infoB

获取 whistle 服务器信息(端口、版本、网络等)

Inputs: no named parameters.

whistle_session_getA

获取单个请求的完整详情(请求头、请求体、响应头、响应体、耗时、规则等),自动解析 query 参数、POST 参数和响应 JSON 字段树

Inputs: id (required).

whistle_sessions_listA

获取最近抓包的 session 列表,可按 URL 或 HTTP 方法过滤

Inputs: count, method, urlFilter.

whistle_statusA

检查 whistle 服务运行状态

Inputs: no named parameters.

whistle_value_getB

获取指定 Value 的内容

Inputs: name (required).

whistle_value_listA

获取 whistle 中所有 Values(键值对)列表

Inputs: no named parameters.

whistle_value_removeC

删除指定 Value

Inputs: name (required).

whistle_value_setA

创建或更新 Value。Value 用于存储 Mock 数据、模板等

Inputs: name (required), content (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 17 tools

    Disambiguation4/5

    The tool set is organized by resource (rules, values, mocks, sessions, server), with clear distinctions between CRUD operations and enabling/disabling. The main ambiguity is whistle_mock_apply overlapping with whistle_rule_enable/disable, but the descriptions clarify the mock-specific scope. Overall, agents should be able to select the right tool.

    Naming Consistency4/5

    Names follow a consistent whistle_<resource>_<action> pattern, with minor deviations: sessions_list (plural) vs session_get (singular), and the separate whistle_status and whistle_server_info break the pattern. These are small inconsistencies but the overall convention is clear and predictable.

    Tool Count4/5

    With 17 tools, the server is slightly above the ideal range, but each tool serves a distinct need in managing Whistle's rules, values, mock setups, and session inspection. The count is justified by the breadth of functionality and does not feel excessive.

    Completeness4/5

    The rule and value tools provide full CRUD plus enable/disable, and session tools cover list/get/search. Mock creation automates the composition of values and rules, though there is no dedicated mock delete/update tool, requiring manual composition of rule/value operations. This is a minor gap that agents can work around.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      C
      maintenance
      Whistle MCP Server is a Whistle proxy management tool based on the Model Context Protocol (MCP) protocol, which enables AI assistants to directly operate and control local Whistle proxy servers. Through this tool, AI can help users manage rules, groups, values, monitor network requests, and replay a
      32
      24 npm
      45
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to configure and manage session-based REST and WebSocket mock servers for application development and testing. It allows for dynamic endpoint setup, request history inspection, and real-time WebSocket communication through natural language commands.
      8
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP-compatible AI assistants to directly search and inspect Whistle-captured HTTP, HTTPS, and WebSocket traffic, including full session details, timing, and frame analysis, without modifying Whistle configuration.
      9 npm
      MIT