ipvolt proxy toolkit MCP Server已验证已精选

什么是 ipvolt Proxy Toolkit MCP？

ipvolt Proxy Toolkit MCP 是一个开源 MCP 服务器，为 AI 智能体提供经过审核的代理文档、经过测试的代理配置模板，以及对代理错误的结构化诊断，无需 API 密钥，也无需代理账户。

它由代理服务商 ipvolt 以 MIT 许可证发布。该工具包独立于 ipvolt 尚未开放的商业代理服务。它不会开通代理、购买流量、读取账户数据，也不会更改其他智能体的网络路由。四个公开工具基于一份随包附带、带版本号的 ipvolt 公开指南目录运行，因此本地服务器不会发起网络请求，也不发送遥测数据。

如何使用 ipvolt Proxy Toolkit MCP？

有三种运行方式：npm 包、从源码构建，或使用托管端点。

npm 包

0.1.0 版本已以 @ipvolt/proxy-toolkit-mcp 发布。README 建议固定版本：

{
  "mcpServers": {
    "ipvolt": {
      "command": "npx",
      "args": ["--yes", "@ipvolt/proxy-toolkit-mcp@0.1.0"]
    }
  }
}

从源码构建

需要 Node.js 24 或更高版本以及 npm。在仓库目录中执行：

npm ci
npm run build
npm run check:content
node dist/transports/stdio.js --version

然后用绝对路径把客户端指向编译后的入口：

{
  "mcpServers": {
    "ipvolt": {
      "command": "node",
      "args": ["/absolute/path/to/proxy-toolkit-mcp/dist/transports/stdio.js"]
    }
  }
}

同样的 mcpServers 配置块适用于 Claude Desktop（claude_desktop_config.json）和 Cursor（~/.cursor/mcp.json）。在 Claude Code 中：

claude mcp add ipvolt -- npx --yes @ipvolt/proxy-toolkit-mcp@0.1.0

托管端点

公开 URL 为 https://mcp.ipvolt.com/mcp（Streamable HTTP），无需注册或 API 密钥，提供四个公开工具。

claude mcp add --transport http ipvolt https://mcp.ipvolt.com/mcp

在 Claude Desktop 或 claude.ai 中，用该 URL 添加自定义连接器。在 Cursor 或 VS Code 中，添加一个 url 条目：

{
  "mcpServers": {
    "ipvolt": {
      "url": "https://mcp.ipvolt.com/mcp"
    }
  }
}

（VS Code 使用 servers 键并加上 "type": "http"。）托管服务会拒绝本地路由诊断，也不接受任何代理配置。

ipvolt Proxy Toolkit MCP 的主要功能

• 搜索和阅读经过审核的代理指南，返回规范链接、摘录和内容修订号。
• 针对 curl 8.22.0、Requests 2.34.2、HTTPX 0.28.1 和 Playwright 1.63.0 的精确版本请求模板，均在受控的认证代理上测试过。
• 模板使用 HTTP 代理加 HTTPS CONNECT，校验目标 TLS，关闭重定向和自动重试，并把目标地址和代理保存在本地 TARGET_URL 和 PROXY_URL 变量中。
• 结构化错误诊断，会说明不确定性和重试边界。
• 一个可选、需显式启用的本地路由检查。
• 本地服务器不发送遥测。托管指标只记录工具名、状态、耗时和版本。

ipvolt Proxy Toolkit MCP 工具

• 文档：search_proxy_docs 搜索经过审核的指南和文章；get_proxy_doc 按有界分块返回指定文档或章节，并提供与修订号绑定的续读游标。
• 配置：generate_proxy_config 返回带本地环境变量占位符的精确版本 HTTPS GET 模板，不会执行代码。
• 诊断：diagnose_proxy_error 解读结构化观察结果，例如 CONNECT 407、TLS 失败或含义不明的超时。
• 路由检查（仅本地）：check_proxy_route 通过你配置的代理向固定回显端点 https://mcp.ipvolt.com/egress 发送一次有界请求，默认关闭。

README 中的示例参数：搜索用 {"query":"curl proxy","topic":"setup"}，诊断用 {"client":"httpx","version":"0.28.1","phase":"proxy_connect","status":407}。

ipvolt Proxy Toolkit MCP 的使用场景

• 配置客户端：“给我一个经过测试、通过 HTTP 代理访问的 HTTPX 0.28.1 示例。”
• 调试故障：“我的 curl 请求经过代理时在 CONNECT 阶段返回 407，这说明什么？”
• 查找指南：“找一下 ipvolt 关于用 curl 设置代理的指南。”
• 检查出口：启用路由检查后，确认一次请求从哪个出口地址发出。

ipvolt Proxy Toolkit MCP 常见问题排查

• 找不到 check_proxy_route：设置 IPVOLT_ENABLE_ROUTE_CHECK=1，并通过客户端的本地环境提供 IPVOLT_PROXY_URL，然后用 {"profile":"default"} 调用。托管服务器上不可用。
• 407 诊断没有指出具体原因：这是有意设计的。407 指向代理认证，但无法判断是密码、账户状态还是访问策略的问题。
• 构建失败：源码构建需要 Node.js 24 或更高版本。
• 托管调用被限流：服务默认每个地址每分钟 120 次请求，请求体上限 32 KiB。