nodemaven-mcp
OfficialA read-only-by-default MCP server for NodeMaven residential proxies, with opt-in write tools for account management.
Build proxy strings with country/region/city/ISP targeting, sticky sessions/TTL, residential or mobile IPs, and HTTP or SOCKS5.
Check proxy connectivity, exit IP, and connection time.
Test a single page through the proxy and report status, size, time, and block indicators.
List available countries, regions, cities, and ISPs with targeting codes.
Read account status, remaining traffic, traffic stats, top domains, sub-users, and whitelisted IPs.
When
NODEMAVEN_MCP_ALLOW_WRITE=1, create/update/reset/delete sub-users and add/remove whitelisted IPs.Keep credentials masked by default, with optional password reveal via
NODEMAVEN_MCP_REVEAL_PASSWORD=1.
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 string for a country, region, city or ISP, with an optional sticky session and its lifetime. Residential or mobile IPs, HTTP or SOCKS5. |
| Opens one connection through the proxy and returns the status, the exit IP and the time it took. Residential or mobile. |
| 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. |
| Countries, regions, cities and ISPs available for targeting, with the codes |
| Remaining traffic, subscription status, whether traffic is frozen. |
| Traffic used over time. |
| Domains reached through the proxy, with traffic per domain. |
| Sub-users with their usage and limits. |
| 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 |
| New sub-user with its own proxy login and an optional traffic limit. The password is generated by the server. |
| Change a sub-user's traffic limit, or turn the limit on or off. |
| Set the recorded traffic of sub-users back to zero. |
| Delete a sub-user. |
| Allow an IP address to use the proxy without a password, with its number of ports and optional targeting. |
| 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.
🎁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 | |
| Required. |
| Optional. Proxy credentials to use instead of the account's own, e.g. a sub-user. |
|
|
|
|
Credentials
Tool results go into the model's context and usually into the chat history, so the server keeps secrets out of them:
proxy_urlandcreate_sub_userreturn the password as<PROXY_PASSWORD>unlessNODEMAVEN_MCP_REVEAL_PASSWORD=1is set.API responses are reduced to a fixed list of fields; proxy passwords and the account email are never returned.
test_proxy_on_sitereturns 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 pytestBuilt on the nodemaven Python SDK.
License
MIT
Available Tools
15 toolsaccount_statusBRead-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_proxyBRead-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_userADestructive
Delete a sub-user. Its proxy login stops working. Cannot be undone.
Inputs: sub_user_id (required). Returns: object
list_locationsARead-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_usersARead-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_ipsARead-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_urlARead-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_ipADestructive
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_usageADestructive
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_siteARead-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_domainsBRead-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_statsBRead-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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Free remote MCP server for fetching public web pages through a rotating proxy pool.
Official MCP server for MAQAMI, a hotel and flight booking platform with 3M+ hotels. Search live hotel rates and flights, look up places, airports and hotel details, then prebook and book. Remote Streamable HTTP endpoint, no API key required.
Public, read-only MCP server for FarmNeural company facts, packages, and capabilities.
Read-only developer, date, finance, and text utilities. Authless remote MCP server by Clean.tools.
Related MCP Servers
- AlicenseAqualityCmaintenanceRead-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.1643 PyPI1MIT
- AlicenseAqualityDmaintenanceMCP 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.5MIT
- AlicenseAqualityBmaintenanceRead-only MCP server to list your SkyNode servers and check their status (IP, state, region, expiry). It does not modify or control servers.2214 npmMIT
- AlicenseBqualityCmaintenanceEnables 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.348 npmMIT