NodeMaven

nodemaven-mcp

An MCP server for NodeMaven residential proxies. It lets an AI assistant build proxy strings with geo-targeting and sticky sessions, check that a proxy connects and where it exits, test it against a site, look up locations, read traffic usage, and manage sub-users and whitelisted IPs.

Read-only by default: the tools that change the account refuse to run until you allow writes.

Tools

Tool	What it does
proxy_url	Proxy string for a country, region, city or ISP, with an optional sticky session and its lifetime. Residential or mobile IPs, HTTP or SOCKS5.
check_proxy	Opens one connection through the proxy and returns the status, the exit IP and the time it took. Residential or mobile.
test_proxy_on_site	Requests one page of a site through the proxy and reports the status, size, time, and whether it looks blocked (403, 429, captcha or challenge page). Residential or mobile. The page is not returned.
list_locations	Countries, regions, cities and ISPs available for targeting, with the codes proxy_url takes.
account_status	Remaining traffic, subscription status, whether traffic is frozen.
traffic_stats	Traffic used over time.
top_domains	Domains reached through the proxy, with traffic per domain.
list_sub_users	Sub-users with their usage and limits.
list_whitelist_ips	IP addresses allowed to use the proxy without a password.

These change the account and work only with NODEMAVEN_MCP_ALLOW_WRITE=1:

Tool	What it does
create_sub_user	New sub-user with its own proxy login and an optional traffic limit. The password is generated by the server.
update_sub_user	Change a sub-user's traffic limit, or turn the limit on or off.
reset_sub_user_usage	Set the recorded traffic of sub-users back to zero.
delete_sub_user	Delete a sub-user.
add_whitelist_ip	Allow an IP address to use the proxy without a password, with its number of ports and optional targeting.
remove_whitelist_ip	Remove an address from the whitelist.

The server has no tools for payments, plans or API keys.

Setup

You need an API key from the NodeMaven dashboard. The proxy username and password are read from the account through that key, so nothing else is required.

[!TIP] 🎁 2 GB of free traffic. No account yet? Sign up and enter the code GITHUB. Once per account.

Claude Desktop (claude_desktop_config.json), Cursor and other MCP clients:

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

Without uv: pip install nodemaven-mcp and use "command": "nodemaven-mcp".

Variable
NODEMAVEN_APIKEY	Required.
NODEMAVEN_LOGIN, NODEMAVEN_PASSWORD	Optional. Proxy credentials to use instead of the account's own, e.g. a sub-user.
NODEMAVEN_MCP_ALLOW_WRITE	1 allows the tools that change the account. Off by default.
NODEMAVEN_MCP_REVEAL_PASSWORD	1 puts real passwords into proxy_url and create_sub_user output. Off by default.

Credentials

Tool results go into the model's context and usually into the chat history, so the server keeps secrets out of them:

• proxy_url and create_sub_user return the password as <PROXY_PASSWORD> unless NODEMAVEN_MCP_REVEAL_PASSWORD=1 is set.
• API responses are reduced to a fixed list of fields; proxy passwords and the account email are never returned.
• test_proxy_on_site returns no page content, and removes the proxy password from connection errors.

Requests to the NodeMaven API name this server and its version in User-Agent, and the name the MCP client gives itself (for example claude-code) once it has given one. Where the SDK's transport cannot be wrapped, the SDK's own User-Agent is sent unchanged. Nothing else about the client or the conversation is sent.

Development

uv sync
uv run pytest

Built on the nodemaven Python SDK.

License

MIT