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.
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_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.
Development
uv sync
uv run pytest
Built on the nodemaven Python SDK.
License
MIT
Metadata
Release files for nodemaven-mcp 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nodemaven_mcp-0.2.0.tar.gz | 14.9 kB | With provenance | Details for nodemaven_mcp-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nodemaven_mcp-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for nodemaven_mcp-0.2.0-py3-none-any.whl |
Total release size: 25.7 kB
Release files / nodemaven_mcp-0.2.0.tar.gz
| Download URL | nodemaven_mcp-0.2.0.tar.gz |
|---|---|
| Size | 14.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
033ee9b72b0a58725c1e8abf49b280f49179b4adc68b1f63b749bc767e4cac19
|
|
BLAKE2b-256 checksum How to use checksums |
aa0d7afe319841683892aca3eb7e723412f9961da80fc20d44876b752533ae3e
|
| 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 27, 2026.
Transparency logRelease files / nodemaven_mcp-0.2.0-py3-none-any.whl
| Download URL | nodemaven_mcp-0.2.0-py3-none-any.whl |
|---|---|
| Size | 10.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e268c3ce74847fa1374f9554af4d66c61d96f49c15b80ab0161ffbf8557ae6dd
|
|
BLAKE2b-256 checksum How to use checksums |
54b95977dc2759eb4dd084af41cf3bc6cf6b0e06b995b32515567167c5951fd9
|
| 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 27, 2026.
Transparency logSecurity for nodemaven-mcp 0.2.0
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.
Attestation for nodemaven_mcp-0.2.0.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 27, 2026.
Transparency logA 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.