Skip to main content
Glama

nodemaven-mcp

2 GB free with code GITHUB

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.

Related MCP server: nodemaven-mcp

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

Available Tools

15 tools
account_statusB
Read-only

Remaining traffic (bytes), subscription status and whether traffic is frozen.

Inputs: no named parameters. Returns: object

add_whitelist_ipA

Allow an IP address to use the proxy without a password. Changes the account.

ports_count is how many proxy ports the address gets. country, region, city
and isp take the codes from list_locations. An address removed in the last
hour can be refused as already whitelisted for a while.

Inputs: ip (required), ports_count (required), isp, city, +4 more. Returns: object

check_proxyB
Read-only

Open one connection through the proxy and report the result.

Sends no traffic through the tunnel. Returns the gateway status, the exit
IP when the gateway reports it, and how long the connection took. A 407 can
mean a wrong parameter value as well as wrong credentials. For mobile, take
the location codes from list_locations with connection_type="mobile".

Inputs: isp, ttl, city, filter, +4 more. Returns: object

create_sub_userA

Create a sub-user with its own proxy login. Changes the account.

The password is generated here. It is returned only if the server allows
revealing passwords; otherwise the user reads it in the dashboard.
traffic_limit is in the same unit list_sub_users shows for traffic_limit and
used_traffic; leave it out for no limit.

Inputs: username (required), traffic_limit. Returns: object

delete_sub_userA
Destructive

Delete a sub-user. Its proxy login stops working. Cannot be undone.

Inputs: sub_user_id (required). Returns: object

list_locationsA
Read-only

List locations available for targeting, with the codes proxy_url takes.

regions need country_code; cities and isps can be narrowed by country_code
and region_code. At most 100 rows per call: when next_offset is returned,
call again with offset=next_offset for the rest.

Inputs: kind (required), limit, offset, region_code, +2 more. Returns: object

list_sub_usersA
Read-only

Sub-users of the account with their traffic usage and limits. No passwords.

Paged from page 1. When next_page is returned, call again with it for the
rest; a page past the end comes back empty.

Inputs: page. Returns: object

list_whitelist_ipsA
Read-only

IP addresses allowed to use the proxy without a password, with their ports and targeting.

Paged from page 1. When next_page is returned, call again with it for the rest.

Inputs: page. Returns: object

proxy_urlA
Read-only

Build a NodeMaven proxy string.

Targeting goes into the username. Without session_id every request gets a
new exit IP; with session_id the same exit is kept for ttl (e.g. "10m",
"1h", "24h"). country is a two-letter code; region, city and isp take the
codes from list_locations. filter is the IP quality filter, e.g. "medium".
connection_type picks residential or mobile IPs; for mobile, take the
location codes from list_locations with connection_type="mobile".
The password is a placeholder unless the server allows revealing it.

Inputs: isp, ttl, city, filter, +5 more. Returns: object

remove_whitelist_ipA
Destructive

Remove an address from the whitelist, by the id list_whitelist_ips or add_whitelist_ip gave.

Inputs: ip_id (required). Returns: object

reset_sub_user_usageA
Destructive

Set the recorded traffic of one or more sub-users back to zero. Changes the account.

Inputs: sub_user_ids (required). Returns: object

test_proxy_on_siteA
Read-only

Request one page of a site through the proxy and say whether it answered.

Sends one GET and reads at most 2 MB. Returns the status, the final URL,
the size and time, and a block reason when the status or the page looks like
a refusal (403, 429, a captcha or a challenge page). The page itself is not
returned. A plain HTTP request is a weaker test than a browser: a site that
needs JavaScript can refuse it and still serve the same proxy in a browser.
For mobile, take the location codes from list_locations with
connection_type="mobile".

Inputs: url (required), isp, ttl, city, +5 more. Returns: object

top_domainsB
Read-only

Domains reached through the proxy, largest traffic first, with bytes and request counts.

Pass period, or start and end as dd-mm-yyyy (not ISO). Defaults to today.

Inputs: end, limit, start, period. Returns: object

traffic_statsB
Read-only

Traffic used over time, as parallel labels and data arrays.

Pass period, or start and end as dd-mm-yyyy (not ISO). Defaults to today.

Inputs: end, start, period. Returns: object

update_sub_userB

Change a sub-user's traffic limit, or turn the limit on or off. Changes the account.

Inputs: sub_user_id (required), traffic_limit, is_traffic_limited. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools target clearly distinct resources and actions, and the descriptions make the boundaries readable. The only notable overlap is between check_proxy and test_proxy_on_site, which both test proxy behavior but differ in scope.

    Naming Consistency4/5

    Names are consistently snake_case, and most action tools follow a verb_noun pattern. A few read-only/analytics tools use noun phrases instead, which is a minor deviation but still predictable.

    Tool Count5/5

    With 15 tools, the set is well-scoped for proxy account management, covering analytics, sub-users, whitelist IPs, and proxy testing. Each tool appears to earn its place without obvious redundancy.

    Completeness4/5

    The surface covers the main lifecycle operations for sub-users and whitelist IPs, plus analytics and proxy testing. Some smaller gaps exist, such as no direct update for whitelist IP targeting or sub-user password reset, but these are workable around via remove/add or dashboard access.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Read-only MCP server for Akamai CDN that enables searching properties, browsing EdgeWorker code, querying DNS zones, inspecting network lists, and translating error codes via natural language.
      16
      43 PyPI
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that lets AI agents route web requests through NodeMaven residential and mobile proxies, with tools for geo-targeted fetching, proxy checking, and location/usage queries.
      5
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Read-only MCP server to list your SkyNode servers and check their status (IP, state, region, expiry). It does not modify or control servers.
      2
      214 npm
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables MCP-compatible clients to list verified free HTTP, SOCKS4, and SOCKS5 proxies, pick top-ranked ones, and summarize the current proxy snapshot through three read-only tools, without forwarding traffic or accepting arbitrary URLs.
      3
      48 npm
      MIT