Metadata-Version: 2.5
Name: nodemaven-mcp
Version: 0.2.1
Summary: MCP server for NodeMaven residential proxies: proxy strings with geo-targeting and sticky sessions, connection and site checks, locations, usage, sub-users and whitelisted IPs.
Project-URL: Source, https://github.com/nodemaven/nodemaven-mcp
License-Expression: MIT
License-File: LICENSE
Keywords: mcp,nodemaven,proxy,residential-proxy,web-scraping
Requires-Python: >=3.10
Requires-Dist: mcp<3,>=2.3
Requires-Dist: nodemaven>=0.1.7
Description-Content-Type: text/markdown

# nodemaven-mcp

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. 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](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** for 2 GB of free traffic, 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
