appsecco/mcp-client-and-proxy

# Appsecco MCP 客户端与代理 [](https://appsecco.com) [](LICENSE) [](https://www.python.org/) ## 这是什么？ **Appsecco MCP 客户端与代理** 是一个安全测试工具，允许你使用 **Burp Suite** 或 **ZAP** 等拦截代理来拦截、检查和修改 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 流量。 它充当一个通用的 MCP 客户端，可以连接到任何 MCP 服务器（本地或远程），并将所有流量路由到你选择的代理以进行安全分析。 ### 主要特性 - **Burp Suite / ZAP 集成** — 将所有 MCP 流量路由到你的拦截代理 - **多种连接模式** — 本地 stdio 服务器、通过 `mcp-remote` 的远程连接，或直接访问 HTTP/SSE 端点 - **完整的流量可见性** — 拦截本地中继流量和后端 HTTPS 流量 - **OAuth 2.1 支持** — 符合 MCP 规范的自动 OAuth 流程（带 PKCE） - **静态头部认证** — API 密钥、Bearer 令牌、自定义头部 - **HTTP/2 支持** — 直接远程连接使用 httpx 并启用 HTTP/2 - **Proxychains 集成** — 通过代理链路由子进程流量 - **会话日志记录** — 所有 CLI 输出同时写入带时间戳的日志文件，便于后续审查 - **交互式 CLI** — 选择服务器、列出工具、带参数调用工具 ## 安装 ### 先决条件 - Python 3.7+ - Node.js 18+ 和 npm（用于基于 `npx` 的 MCP 服务器） - [Proxychains](https://github.com/haad/proxychains)（可选，用于路由子进程流量） - Burp Suite 或 ZAP（用于流量拦截） ### 设置 ``` # 克隆仓库 git clone https://github.com/appsecco/mcp-client-and-proxy.git cd mcp-client-and-proxy # 创建并激活虚拟环境 python3 -m venv venv && source venv/bin/activate # 安装 Python 依赖 pip3 install -r requirements.txt # 安装 Node.js 依赖（用于后端流量拦截） npm install -g global-agent npm install undici ``` ### 安装 Proxychains（可选） - **macOS**: `brew install proxychains-ng` - **Ubuntu/Debian**: `sudo apt-get install proxychains` - **CentOS/RHEL**: `sudo yum install proxychains` ## 快速开始 ### 1. 配置 MCP 服务器 创建或编辑 `mcp_config.json`： ``` { "mcpServers": { "my-remote-mcp": { "url": "https://remote.example.com/mcp" } } } ``` ### 2. 启动 Burp Suite 启动 Burp Suite 并监听 `127.0.0.1:8080`（默认设置）。 ### 3. 运行工具 ``` # 对于远程 MCP 服务器（直接远程模式） python3 app.py # 对于本地 stdio / mcp-remote 服务器（在端口 3000 启动本地代理） python3 app.py --start-proxy ``` ### 4. 交互 该工具会显示一个交互式菜单： ``` 🔧 Appsecco MCP Client PST - Professional Security Testing ------------------------------------------------------------ Choose an option: 1. 🛠️ Call a tool 2. 📋 List tools again 3. 🔄 Switch server 4. 🚪 Exit 5. ℹ️ About Appsecco ``` 选择一个工具，提供参数，并观察流量在 Burp 中显示。 ## 连接模式 工具会根据 `mcp_config.json` 自动检测连接模式： | 模式 | 配置 | 是否使用子进程 | 用途 | |---|---|---|---| | **direct-remote** | `url` 字段（无 `command`） | 否 | 远程 HTTP/SSE MCP 端点 | | **mcp-remote** | `command: npx` 并包含 `mcp-remote` 参数 | 是 | 通过 npm 桥接远程 MCP | | **stdio** | `command` 加 `args` | 是 | 本地 MCP 服务器 | ### 直接远程连接 直接连接到一个 HTTP/SSE MCP 端点。不需要子进程或本地代理 — 请求直接通过 Burp 发送到远程服务器。 ``` { "mcpServers": { "my-remote-mcp": { "url": "https://remote.example.com/mcp" } } } ``` ### 本地 stdio 服务器 运行一个本地 MCP 服务器进程，并通过 stdin/stdout 通信。使用 `--start-proxy` 通过本地 HTTP 代理（端口 3000）将流量路由到 Burp。 ``` { "mcpServers": { "local-server": { "command": "python", "args": ["my_mcp_server.py"] } } } ``` ### 通过 mcp-remote 的远程连接 使用 `mcp-remote` npm 包作为远程端点的桥接。添加 `env` 变量以将后端流量路由到 Burp（参见 [拦截后端流量](#intercepting-backend-mcp-server-traffic-mcp-remote)）。 ``` { "mcpServers": { "remote-via-bridge": { "command": "npx", "args": ["-y", "mcp-remote", "https://remote.example.com/mcp"], "env": { "NODE_EXTRA_CA_CERTS": "/path/to/burp-ca.pem", "NODE_OPTIONS": "--require /path/to/proxy-bootstrap.js", "GLOBAL_AGENT_HTTP_PROXY": "http://127.0.0.1:8080", "GLOBAL_AGENT_HTTPS_PROXY": "http://127.0.0.1:8080" } } } } ``` ## 认证 ### 静态头部 为每个请求添加 API 密钥、Bearer 令牌或自定义头部： ``` { "mcpServers": { "authenticated-mcp": { "url": "https://remote.example.com/mcp", "headers": { "Authorization": "Bearer your-api-key-or-token", "X-Custom-Header": "value" } } } } ``` ### OAuth 2.1（自动） 如果远程服务器返回 `401 Unauthorized` 并附带 `WWW-Authenticate: Bearer` 头部，该工具会自动运行 [MCP OAuth 2.1 流程](https://modelcontextprotocol.io/specification/draft/basic/authorization)： 1. 发现受保护资源元数据（RFC 9728） 2. 获取授权服务器元数据 3. 如果未配置客户端 ID，则尝试动态客户端注册（RFC 7591） 4. 打开浏览器进行授权码 + PKCE 登录 5. 交换代码以获取访问令牌并重试请求 要使用预注册的 OAuth 凭据： ``` { "mcpServers": { "oauth-mcp": { "url": "https://remote.example.com/mcp", "oauth_client_id": "your-client-id", "oauth_client_secret": "your-client-secret" } } } ``` | 配置字段 | 是否必需 | 用途 | |---|---|---| | `headers` | 否 | 每个请求发送的静态 HTTP 头部 | | `oauth_client_id` | 否 | 预注册的 OAuth 客户端 ID（跳过动态注册） | | `oauth_client_secret` | 否 | OAuth 客户端密钥（用于机密客户端） | ## 数据流 ### 直接远程模式 ``` App → Burp (port 8080) → Remote MCP endpoint ``` ### stdio / mcp-remote 模式（带 --start-proxy） ``` App → Local Proxy (port 3000) → Burp (port 8080) → MCP Server (stdio) ↓ mcp-remote subprocess ↓ Burp (port 8080) → Remote MCP endpoint ``` ## 拦截后端 MCP 服务器流量（mcp-remote） 默认情况下，`proxychains` 无法拦截 Node.js 流量，因为 Node.js 使用自己的网络栈（libuv/undici），绕过了 `LD_PRELOAD`/`DYLD_INSERT_LIBRARIES` 钩子。此工具通过以下方式解决该问题： - **`HTTP_PROXY`/`HTTPS_PROXY` 环境变量** — 自动设置在 MCP 子进程上 - **`proxy-bootstrap.js`** — 同时修补 Node.js 的遗留 `http`/`https` 模块（通过 `global-agent`）和原生 `fetch`/`undici` 分发器（通过 `undici` 的 `ProxyAgent`） ### 设置步骤 **步骤 1：导出 Burp 的 CA 证书为 PEM 格式** 在 Burp Suite 中：`Proxy → Options → Import/export CA certificate → Export Certificate in DER format` ``` openssl x509 -inform DER -in burp-ca.crt -out burp-ca.pem ``` **步骤 2：查找 global-agent 的安装路径** ``` npm root -g # 例如 /usr/local/lib/node_modules ``` **步骤 3：更新 `proxy-bootstrap.js`** 编辑 `require(...)` 路径以匹配你的系统： ``` const { bootstrap } = require('/path/to/node_modules/global-agent'); bootstrap(); const { ProxyAgent, setGlobalDispatcher } = require('undici'); const proxyUrl = process.env.GLOBAL_AGENT_HTTPS_PROXY || 'http://127.0.0.1:8080'; setGlobalDispatcher(new ProxyAgent(proxyUrl)); ``` **步骤 4：配置 `mcp_config.json`** 向你的 MCP 服务器条目添加 `env` 块： ``` { "mcpServers": { "My MCP Server": { "command": "npx", "args": ["-y", "mcp-remote", "https://your-mcp-server.example.com/mcp"], "env": { "NODE_EXTRA_CA_CERTS": "/path/to/burp-ca.pem", "NODE_OPTIONS": "--require /path/to/proxy-bootstrap.js", "GLOBAL_AGENT_HTTP_PROXY": "http://127.0.0.1:8080", "GLOBAL_AGENT_HTTPS_PROXY": "http://127.0.0.1:8080" } } } } ``` | 字段 | 用途 | |---|---| | `NODE_EXTRA_CA_CERTS` | 信任 Burp 的 CA 证书，使 TLS 验证通过代理 | | `NODE_OPTIONS` | 在其他代码运行前加载 `proxy-bootstrap.js` | | `GLOBAL_AGENT_HTTP_PROXY` / `GLOBAL_AGENT_HTTPS_PROXY` | `global-agent` 和 `proxy-bootstrap.js` 的代理 URL | 配置完成后，所有流量（包括通过 `mcp-remote` 到远程端点的 HTTPS 流量）都会显示在 Burp 中。 ## CLI 选项 ``` python3 app.py [OPTIONS] Options: -h, --help Show help message --config CONFIG, -c CONFIG MCP config file (default: mcp_config.json) --proxy PROXY, -p PROXY Burp/ZAP proxy URL (default: http://127.0.0.1:8080) --start-proxy Start local HTTP proxy server for Burp inspection --proxy-port PROXY_PORT Local proxy server port (default: 3000) --no-burp Disable routing through Burp/ZAP proxy --no-proxychains Disable proxychains for subprocess traffic --no-ssl-bypass Keep SSL certificate verification enabled --no-analytics Disable anonymous usage analytics --debug Enable verbose debug output --log-file LOG_FILE, -l LOG_FILE Path to session log file (default: logs/session_.log) ``` ### 示例 ``` # 使用 Burp 拦截的标准用法（本地服务器） python3 app.py --start-proxy # 直接远程 MCP（无需本地代理） python3 app.py # 自定义配置文件 python3 app.py --config my_servers.json --start-proxy # 自定义代理 URL（例如端口 8081 上的 ZAP） python3 app.py --proxy http://127.0.0.1:8081 --start-proxy # 无 Burp（仅直接连接） python3 app.py --no-burp --no-proxychains # 调试模式用于故障排除 python3 app.py --debug --start-proxy # 将会话日志写入自定义路径 python3 app.py --log-file /tmp/my-session.log ``` ## 会话日志 每次运行都会将所有 CLI 输出（标准输出 + 标准错误）镜像到日志文件中，以便后续回顾或与团队成员共享发现。 - **默认路径**：`logs/session_.log`（`logs/` 目录会自动创建） - **覆盖**：`python3 app.py --log-file /path/to/session.log`（或 `-l`） - **内容**：终端打印的所有内容 — 横幅、菜单选择、工具调用、响应、错误 — 并去除 ANSI 颜色转义以便阅读 - **追加安全**：每次运行添加 `===== Session started (pid ) =====` 标题，使重复文件可追溯 - **Git 忽略**：`logs/` 和 `*.log` 已在 `.gitignore` 中，因此会话输出不会意外提交 ## 分析 该工具包含可选的匿名使用分析。 **记录内容**：启动参数、会话开始/结束、MCP 服务器数量、错误率、基本系统信息（操作系统、Python 版本） **不记录内容**：个人数据、URL、测试目标、流量内容、凭据 **退出分析**： ``` python3 app.py --no-analytics # 或 export MCP_ANALYTICS_DISABLED=true ``` **调试分析**（查看发送的数据）： ``` export MCP_ANALYTICS_DEBUG=true ``` ## 我们为何构建此工具 [](https://youtu.be/A3DpnyEfC4M) 我们在为一家财富 500 强金融科技公司测试 MCP 服务器安全性时构建了此工具。它在我们的 Burp Suite 工作流中运行良好，我们认为安全社区的其他人也能从中受益。 ## 关于 Appsecco **Appsecco** 是一家专注于以下领域的领先网络安全公司： - **AI 代理、AI 优先应用和 MCP 服务器渗透测试** - **渗透测试与安全评估** - **应用程序安全测试** - **基础设施渗透测试** - **云安全评估** 此 MCP 客户端代理工具是我们专业安全工具包的一部分，旨在为安全研究人员、渗透测试人员和网络安全专业人士提供一款能够拦截和代理 MCP 本地和远程服务器流量的工具，通过 Burp/ZAP 等拦截代理进行操作。 ### 联系方式 - **网站**：[https://appsecco.com](https://appsecco.com) - **电子邮件**：[contact@appsecco.com](mailto:contact@appsecco.com) - **LinkedIn**：[https://linkedin.com/company/appsecco](https://linkedin.com/company/appsecco) - **博客**：[https://blog.appsecco.com](https://blog.appsecco.com) - **Twitter**：[@appseccouk](https://twitter.com/appseccouk) ## 许可证 本项目根据 MIT 许可证授权 — 详见 [LICENSE](LICENSE) 文件。 ## 感谢 由 **[Riyaz](https://github.com/riyazwalikar) & [Akash](https://github.com/makash)** 为网络安全社区构建。 **Appsecco — 我们在攻击者之前测试你的产品与基础设施**

标签：API密钥, Bearer令牌, Burp Suite, GNU通用公共许可证, HTTP/2, MCP客户端, MCP远程, MITM代理, Node.js, OAuth 2.1, PKCE, Proxychains, Python, SSE, STDIO, 中间人, 交互式CLI, 代理, 会话日志, 安全测试, 攻击性安全, 无后门, 无文件攻击, 模型上下文协议, 流量可见性, 流量拦截, 虚拟环境, 逆向工具, 静态头认证