Skip to main content

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. HTTP or SOCKS5.
check_proxy Opens one connection through the proxy and returns the status, the exit IP and the time it took.
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). 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. No account yet? Sign up and enter the code GITHUB for 2 GB of free traffic, 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.

Development

uv sync
uv run pytest

Built on the nodemaven Python SDK.

License

MIT

Metadata

Release files for nodemaven-mcp 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nodemaven-mcp 0.2.1
File Size Uploaded Provenance Actions
nodemaven_mcp-0.2.1.tar.gz 15.3 kB With provenance Details for nodemaven_mcp-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nodemaven-mcp 0.2.1
File Interpreter ABI Platform Actions
nodemaven_mcp-0.2.1-py3-none-any.whl Python 3 none any Details for nodemaven_mcp-0.2.1-py3-none-any.whl

Total release size: 26.3 kB

Release files / nodemaven_mcp-0.2.1.tar.gz

Download URL nodemaven_mcp-0.2.1.tar.gz
Size 15.3 kB
Tags Source
SHA-256 checksum
How to use checksums
5b001f4a6ca4f16aeabfcf79189189716d1e274262300f3987869eae8cfde3a1
BLAKE2b-256 checksum
How to use checksums
e02fd39f40fa9d7ef792728ac7d73e4bba676686965b228ffb940ff1610dff3e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Release files / nodemaven_mcp-0.2.1-py3-none-any.whl

Download URL nodemaven_mcp-0.2.1-py3-none-any.whl
Size 11.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3e6eff8dfe3971558677eca9b58029250ec72fb5a2d9aaafd440ae94001129d8
BLAKE2b-256 checksum
How to use checksums
8ecef8e1ce2dd4de803a5b79c1ac9b4690491a4fb0563881cf92e3a6ec516943
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Security for nodemaven-mcp 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for nodemaven_mcp-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page