Whistle MCP Server

Whistle MCP 服务

English | 中文

项目介绍

Whistle MCP 服务是一款基于 Model Context Protocol（MCP）的 Whistle 代理管理工具，可让 AI 助手直接操作和控制本地 Whistle 代理服务。借助此工具，AI 可以帮助用户管理规则、分组和值，监控网络请求，重放和修改请求等，无需手动操作 Whistle 界面。它大幅简化了网络调试、API 测试和代理规则管理流程，让用户能够通过与 AI 的自然语言交互，完成复杂的网络代理配置任务。

功能特性

• 规则管理：创建、更新、重命名、删除和启用/停用 Whistle 规则
• 分组管理：创建、重命名和删除分组，并管理规则与分组之间的关联
• 值管理：创建、更新、重命名和删除值，并支持值分组管理
• 代理控制：启用/停用代理、HTTP/HTTPS 拦截、HTTP/2 协议等
• 请求拦截：查看拦截到的网络请求信息，并支持按 URL 筛选
• 请求重放：支持使用自定义请求参数重放已捕获的请求
• 多规则模式：支持启用/停用多规则模式

安装

要求

需要 Node.js 18.20.0 或更高版本（请参阅 package.json 中的 engines）。不支持更早的版本。

通过 Smithery 安装

通过 Smithery 为 Claude Desktop 自动安装 Whistle MCP 服务：

npx -y @smithery/cli install @7gugu/whistle-mcp --client claude

手动安装

你可以通过 npm 全局安装 Whistle MCP 服务：

npm install -g whistle-mcp-tool

从源代码构建

在仓库根目录中运行：

npm install
npm run build

构建输出入口为 dist/index.js（全局安装后，whistle-mcp CLI 使用的文件）。你也可以在 MCP 配置中通过 node 和 dist/index.js 的路径来指定它。

MCP 配置

传输方式（stdio 与 HTTP）

默认情况下，服务使用 stdio（适用于 Cursor 等本地 MCP 客户端）。

若要在同一进程中提供 Streamable HTTP 和 SSE，以供远程或支持 HTTP 的客户端使用，请使用 --transport http-stream。FastMCP 随后会在 --mcp-host / --mcp-port 上监听，并提供：

• Streamable HTTP：http://<mcp-host>:<mcp-port><mcp-endpoint>（默认路径为 /mcp）
• SSE：http://<mcp-host>:<mcp-port>/sse

http-stream 的别名：sse、streamable-http（相同模式；两个 URL 均可使用）。

标志 / 环境变量	含义
--transport / -t、FASTMCP_TRANSPORT	stdio（默认）或 http-stream
--mcp-port、FASTMCP_PORT	MCP HTTP 端口（使用 HTTP 传输时默认为 8085）
--mcp-host、FASTMCP_HOST	绑定地址（默认为 0.0.0.0）
--mcp-endpoint、FASTMCP_ENDPOINT	Streamable HTTP 路径（默认为 /mcp）
--stateless、FASTMCP_STATELESS=true	无状态 HTTP 模式（可选）

Whistle 连接选项保持不变：--host、--port、--username / --password（或 -n / -w）。

示例（使用 HTTP 传输 + 在本地运行的 Whistle，端口为 8899；MCP 默认监听 8085）：

whistle-mcp --transport http-stream --host 127.0.0.1 --port 8899

使用 --mcp-port <port> 可覆盖默认端口 8085。

安装后，你可以在 MCP JSON 配置文件中配置 Whistle MCP：

{
  "mcpServers": {
    "whistle-mcp": {
      "command": "whistle-mcp",
      "args": [
        "--host=<whistle server IP address>",
        "--port=<whistle server port number>"
      ]
    }
  }
}

如果你使用基本身份验证启动 Whistle（与 Whistle CLI 中的标志相同：w2 start -n <username> -w <password>），请向此 MCP 服务传入相同的凭据，以确保对 Whistle API 的 HTTP 请求成功：

{
  "mcpServers": {
    "whistle-mcp": {
      "command": "whistle-mcp",
      "args": [
        "--host=localhost",
        "--port=8899",
        "--username=<username>",
        "--password=<password>"
      ]
    }
  }
}

短选项（与 w2 一致）：-n / -w 等同于 --username / --password。

whistle-mcp --host localhost --port 8899 -n myuser -w mypass

配置详情

• host：Whistle 服务 IP 地址；如果省略，默认为 localhost
• port：Whistle 服务端口；如果省略，默认为 8899
• username（-n / --username）：Whistle 使用 -n 启动时的基本身份验证用户名；如果 Whistle 未启用登录，则省略
• password（-w / --password）：Whistle 使用 -w 启动时的基本身份验证密码；如果已设置用户名但省略密码，则会发送空密码

在 AI 客户端中配置 MCP JSON

• Claude Client：https://modelcontextprotocol.io/quickstart/user
• Raycast：需要安装 MCP 插件
• Cursor：https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers

MCP 工具说明

Whistle MCP Server 提供以下工具，可通过 MCP 协议调用：

规则管理

工具名称	描述	功能
getRules	获取所有规则	列出所有已创建的规则及其内容
createRule	创建新规则	创建指定名称的新规则
updateRule	更新规则内容	修改指定规则的内容
renameRule	重命名规则	将规则重命名为新名称
deleteRule	删除规则	删除指定名称的规则
enableRule	启用规则	启用指定名称的规则
disableRule	禁用规则	禁用指定名称的规则
setAllRulesState	设置所有规则状态	一次性启用或禁用所有规则

分组管理

工具名称	描述	功能
createGroup	创建分组	创建指定名称的新规则组
renameGroup	重命名分组	将规则组重命名为新名称
deleteGroup	删除分组	删除指定名称的规则组
addRuleToGroup	将规则添加到分组	将指定规则添加到特定分组
removeRuleFromGroup	从分组中移除规则	将规则从其所在分组移至顶层

值管理

工具名称	描述	功能
getAllValues	获取所有值	列出所有已创建的值和值组（注意：数据可能较大，可先使用 getValueList）
getValueList	获取值列表	仅获取值的索引和名称（不包含数据字段，以避免载荷过大）
getValue	获取单个值	按名称获取单个值的完整信息（包括数据字段）
createValue	创建新值	创建指定名称的新值
updateValue	更新值内容	修改指定值的内容
renameValue	重命名值	将值重命名为新名称
deleteValue	删除值	删除指定名称的值
createValuesGroup	创建值组	创建指定名称的新值组
renameValueGroup	重命名值组	将值组重命名为新名称
deleteValueGroup	删除值组	删除指定名称的值组
addValueToGroup	将值添加到分组	将指定值添加到特定分组
removeValueFromGroup	从分组中移除值	将值从其所在分组移至顶层

代理控制

工具名称	描述	功能
getWhistleStatus	获取服务状态	获取 Whistle 服务的当前状态信息
toggleProxy	启用/禁用代理	切换 Whistle 代理的启用状态
toggleHttpInterception	启用/禁用 HTTP 拦截	切换 HTTP 请求拦截的启用状态
toggleHttpsInterception	启用/禁用 HTTPS 拦截	切换 HTTPS 请求拦截的启用状态
toggleHttp2	启用/禁用 HTTP2	切换 HTTP/2 协议支持的启用状态
toggleMultiRuleMode	启用/禁用多规则模式	切换是否允许同时启用多条规则

请求管理

工具名称	描述	功能
getInterceptInfo	获取拦截信息	获取 Whistle 拦截的网络请求信息，支持 URL 过滤和正则表达式
replayRequest	重放请求	使用可自定义的参数重新发送指定的网络请求

实用工具

工具名称	描述	功能
getCurrentTimestamp	获取当前时间戳	获取当前本地时间戳

联系方式

• 电子邮件：[email protected]
• 博客：https://7gugu.com