NodeMaven

nodemaven-mcp

面向 NodeMaven 住宅代理的 MCP 服务。 它可让 AI 助手生成支持地理位置定位和粘性会话的代理字符串，检查代理是否连接成功以及出口位置，通过代理测试网站，查询可用位置、读取流量用量，并管理子用户和 IP 白名单。

默认只读：在允许写入之前，更改账户的工具不会运行。

工具

工具	功能
proxy_url	生成适用于指定国家、地区、城市或 ISP 的代理字符串，可选粘性会话及其有效期。支持 HTTP 或 SOCKS5。
check_proxy	通过代理建立一次连接，并返回状态、出口 IP 和耗时。
test_proxy_on_site	通过代理请求网站的一个页面，并报告状态、大小、耗时，以及页面是否看起来遭到拦截（403、429、验证码或质询页面）。不会返回页面内容。
list_locations	查询可用于定位的国家、地区、城市和 ISP，以及 proxy_url 接受的代码。
account_status	查询剩余流量、订阅状态，以及流量是否被冻结。
traffic_stats	查询一段时间内的流量用量。
top_domains	查询通过代理访问过的域名，以及每个域名的流量。
list_sub_users	查询子用户及其用量和限额。
list_whitelist_ips	查询可免密码使用代理的 IP 地址。

以下工具会更改账户，只有设置 NODEMAVEN_MCP_ALLOW_WRITE=1 后才可使用：

工具	功能
create_sub_user	创建拥有独立代理登录信息的新子用户，可选设置流量限额。密码由服务生成。
update_sub_user	更改子用户的流量限额，或开启、关闭限额。
reset_sub_user_usage	将子用户记录的流量重置为零。
delete_sub_user	删除子用户。
add_whitelist_ip	允许某个 IP 地址免密码使用代理，并设置端口数量和可选的定位条件。
remove_whitelist_ip	从白名单中移除某个地址。

此服务不提供支付、套餐或 API 密钥相关工具。

设置

你需要从 NodeMaven 控制面板获取 API 密钥。代理用户名和密码会通过此密钥从账户中读取，因此无需其他信息。

Claude Desktop（claude_desktop_config.json）、Cursor 及其他 MCP 客户端：

{
  "mcpServers": {
    "nodemaven": {
      "command": "uvx",
      "args": ["nodemaven-mcp"],
      "env": { "NODEMAVEN_APIKEY": "your-api-key" }
    }
  }
}

若不使用 uv：运行 pip install nodemaven-mcp，并使用 "command": "nodemaven-mcp"。

变量
NODEMAVEN_APIKEY	必需。
NODEMAVEN_LOGIN, NODEMAVEN_PASSWORD	可选。指定要使用的代理凭据，以替代账户自身的凭据，例如子用户的凭据。
NODEMAVEN_MCP_ALLOW_WRITE	设置为 1 后允许使用会更改账户的工具。默认关闭。
NODEMAVEN_MCP_REVEAL_PASSWORD	设置为 1 后，proxy_url 和 create_sub_user 的输出会包含真实密码。默认关闭。

凭据

工具结果会进入模型的上下文，通常也会进入聊天记录，因此此服务会避免在结果中暴露机密信息：

• 除非设置 NODEMAVEN_MCP_REVEAL_PASSWORD=1，否则 proxy_url 和 create_sub_user 会以 <PROXY_PASSWORD> 替代密码。
• API 响应会精简为固定字段列表；绝不会返回代理密码和账户邮箱。
• test_proxy_on_site 不会返回页面内容，并会从连接错误中移除代理密码。

开发

uv sync
uv run pytest

基于 nodemaven Python SDK 构建。

许可证

MIT