English Français العربية

NodeMaven

Official registry Maps, travel and weather

NodeMaven residential proxies: geo-targeted proxy URLs, sticky sessions, checks and usage

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package nodemaven-mcp
Claude Code 
claude mcp add nodemaven -e 'NODEMAVEN_APIKEY=<your nodemaven_apikey>' -e 'NODEMAVEN_MCP_ALLOW_WRITE=<NODEMAVEN_MCP_ALLOW_WRITE>' -e 'NODEMAVEN_MCP_REVEAL_PASSWORD=<NODEMAVEN_MCP_REVEAL_PASSWORD>' -- uvx nodemaven-mcp==0.2.0
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "nodemaven": {
            "command": "uvx",
            "args": [
                "nodemaven-mcp==0.2.0"
            ],
            "env": {
                "NODEMAVEN_APIKEY": "<your nodemaven_apikey>",
                "NODEMAVEN_MCP_ALLOW_WRITE": "<NODEMAVEN_MCP_ALLOW_WRITE>",
                "NODEMAVEN_MCP_REVEAL_PASSWORD": "<NODEMAVEN_MCP_REVEAL_PASSWORD>"
            }
        }
    }
}

Environment variables

  • NODEMAVEN_APIKEY required secret API key from the NodeMaven dashboard
  • NODEMAVEN_MCP_ALLOW_WRITE Set to 1 to allow the tools that change the account (sub-users, whitelisted IPs)
  • NODEMAVEN_MCP_REVEAL_PASSWORD Set to 1 to include real proxy passwords in proxy_url and create_sub_user results

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. nodemaven-mcp
  2. Tools
  3. Setup
  4. Credentials
  5. Development
  6. License

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, look up locations, and read traffic usage.

It is read-only: nothing in your account is created, changed or deleted.

Tools

ToolWhat it does
proxy_urlProxy string for a country, region, city or ISP, with an optional sticky session and its lifetime. HTTP or SOCKS5.
check_proxyOpens one connection through the proxy and returns the status, the exit IP and the time it took.
list_locationsCountries, regions, cities and ISPs available for targeting, with the codes proxy_url takes.
account_statusRemaining traffic, subscription status, whether traffic is frozen.
traffic_statsTraffic used over time.
top_domainsDomains reached through the proxy, with traffic per domain.
list_sub_usersSub-users with their usage and limits.

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.

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_APIKEYRequired.
NODEMAVEN_LOGIN, NODEMAVEN_PASSWORDOptional. Proxy credentials to use instead of the account's own, e.g. a sub-user.
NODEMAVEN_MCP_REVEAL_PASSWORD1 puts the real password into proxy_url 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 returns 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.

Development

uv sync
uv run pytest

Built on the nodemaven Python SDK.

License

MIT

Frequently asked questions

What is NodeMaven?

NodeMaven residential proxies: geo-targeted proxy URLs, sticky sessions, checks and usage

How do I install NodeMaven?

It runs on your machine. In Claude Code: claude mcp add nodemaven -e 'NODEMAVEN_APIKEY=<your nodemaven_apikey>' -e 'NODEMAVEN_MCP_ALLOW_WRITE=<NODEMAVEN_MCP_ALLOW_WRITE>' -e 'NODEMAVEN_MCP_REVEAL_PASSWORD=<NODEMAVEN_MCP_REVEAL_PASSWORD>' -- uvx nodemaven-mcp==0.2.0. For other clients, paste the JSON configuration from this page into their MCP settings.

Does NodeMaven need an API key?

Yes. It expects NODEMAVEN_APIKEY, which you set in its configuration.

Is NodeMaven open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains NodeMaven?

It is published by nodemaven. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.