Metadata-Version: 2.5
Name: nodemaven-mcp
Version: 0.2.0
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.

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
