# nodemaven-mcp

[![2 GB free with code GITHUB](https://img.shields.io/badge/%F0%9F%8E%81%202%20GB%20free-code%20GITHUB-1153FC)](https://dashboard.nodemaven.com/accounts/signup/?utm_source=github&utm_medium=readme&utm_campaign=nodemaven_mcp&utm_content=promo_badge)

An [MCP](https://modelcontextprotocol.io) server for [NodeMaven](https://nodemaven.com)
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.

<!-- mcp-name: io.github.nodemaven/nodemaven-mcp -->

## 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.

## 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](https://dashboard.nodemaven.com/accounts/signup/?utm_source=github&utm_medium=readme&utm_campaign=nodemaven_mcp&utm_content=signup_promo) and enter the code **GITHUB**. Once per account.

Claude Desktop (`claude_desktop_config.json`), Cursor and other MCP clients:

```json
{
  "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

```bash
uv sync
uv run pytest
```

Built on the [`nodemaven`](https://pypi.org/project/nodemaven/) Python SDK.

## License

MIT