NodeMaven

io.github.nodemavenv0.1.0Updated Oct 6, 2026

NodeMaven residential proxies: geo-targeted proxy URLs, sticky sessions, checks and usage

VerifiedSTDIODesktop onlyCloud & InfrastructureWeb Search & Scraping

Overview

AI-generated overview

Lets an assistant build geo-targeted NodeMaven residential proxy URLs, test proxy connections, and read account traffic usage.

What it does
Wraps the NodeMaven residential proxy service. Tools build proxy strings for a country, region, city or ISP with optional sticky sessions and HTTP or SOCKS5, open a test connection to report status, exit IP and latency, list available targeting locations, and read account status, traffic statistics, top domains and sub-user usage. It is read-only: nothing in the account is created, changed or deleted.
When to use it
Useful when an assistant needs to construct or verify residential proxy connections for a given location, or to report on proxy traffic and usage without opening the NodeMaven dashboard.
Requirements
Runs locally over stdio, typically via uvx or pip install of the nodemaven-mcp package, so Python and an MCP client such as Claude Desktop or Cursor are needed. A NodeMaven API key is required in the NODEMAVEN_APIKEY environment variable; optional NODEMAVEN_LOGIN and NODEMAVEN_PASSWORD can supply alternate proxy credentials. Network access to NodeMaven is required.
Before you install
The API key in NODEMAVEN_APIKEY grants access to the account and its proxy credentials. Tool results enter the model context and chat history, so the server masks the proxy password as a placeholder unless NODEMAVEN_MCP_REVEAL_PASSWORD=1 is set, which exposes the real password; leave it off unless needed. Proxy traffic is billed against the account's remaining traffic.

Installation

In SourceWeft

  1. Open NodeMaven in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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, look up locations, and read traffic usage.

It is read-only: nothing in your account is created, changed or deleted.

Tools

ToolWhat it does
proxy_urlProxy string for a country, region, city or ISP, with an optional sticky session and its lifetime. HTTP or SOCKS5.
check_proxyOpens one connection through the proxy and returns the status, the exit IP and the time it took.
list_locationsCountries, regions, cities and ISPs available for targeting, with the codes proxy_url takes.
account_statusRemaining traffic, subscription status, whether traffic is frozen.
traffic_statsTraffic used over time.
top_domainsDomains reached through the proxy, with traffic per domain.
list_sub_usersSub-users with their usage and limits.

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_APIKEYRequired.
NODEMAVEN_LOGIN, NODEMAVEN_PASSWORDOptional. Proxy credentials to use instead of the account's own, e.g. a sub-user.
NODEMAVEN_MCP_REVEAL_PASSWORD1 puts the real password into proxy_url 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 returns 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.

Development

bash
uv syncuv run pytest

Built on the nodemaven Python SDK.

License

MIT

Source: README.md at commit 9ac70d5

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.1.0LatestOct 6, 2026