Skip to main content
Glama
nodemaven-mcp

nodemaven-mcp

by Artirain

nodemaven-mcp

CI Python 3.10+ License: MIT

English | Русский

Give your AI agent a residential IP. An MCP server that lets Claude Code, Claude Desktop, Cursor or any other MCP client route web requests through NodeMaven residential and mobile proxies: pick an exit country, verify what the target site sees, and pull the page.

you:    read this product page the way a shopper in Munich sees it
agent:  nodemaven_fetch(url=..., country="de", city="munich")
        -> 200, de, 14.99 EUR, exit IP 91.34.x.x (Vodafone), 812 ms

Unofficial, community-built, MIT licensed. Not affiliated with NodeMaven.


Why

Agents are increasingly the thing doing the browsing, and they hit the same wall everyone else does: datacenter IPs get blocked, and prices, stock and search results change by geography. The proxy is already the fix - it just isn't reachable from inside the agent's session.

This server closes that gap in five tools. Nothing here needs a scraping DSL: the agent asks for a country, gets a working connection, and reads the page.

Related MCP server: proxyclaw-mcp-py

Tools

Tool

What it does

Needs

nodemaven_build_proxy_url

Builds a proxy URL with geo targeting encoded in the username, ready for curl, Playwright, Scrapy or requests

proxy creds

nodemaven_check_proxy

One request through the proxy: exit IP, geo, ISP, latency

proxy creds

nodemaven_fetch

Fetches a URL through the proxy, HTML converted to readable text

proxy creds

nodemaven_list_locations

Countries, regions, cities, ISPs, zip codes available for targeting

API key

nodemaven_get_usage

Traffic consumed, request counts, per-domain breakdown

API key

Every tool takes response_format: markdown (default, compact) or json (complete, for programmatic use), and paginates with limit / offset.

Install

git clone https://github.com/Artirain/nodemaven-mcp
cd nodemaven-mcp
pip install -e .

Requires Python 3.10+.

Configure

Two independent sets of credentials, both from the NodeMaven dashboard:

  • NODEMAVEN_API_KEY - Profile -> API Key. Used by the location and usage tools.

  • NODEMAVEN_PROXY_USERNAME / NODEMAVEN_PROXY_PASSWORD - Proxy Setup. Used by everything that sends traffic through the proxy.

You can set only one set; tools that need the other say so instead of failing silently.

Claude Code

claude mcp add nodemaven \
  -e NODEMAVEN_API_KEY=... \
  -e NODEMAVEN_PROXY_USERNAME=... \
  -e NODEMAVEN_PROXY_PASSWORD=... \
  -- python -m nodemaven_mcp

Claude Desktop / Cursor

claude_desktop_config.json (or .cursor/mcp.json):

{
  "mcpServers": {
    "nodemaven": {
      "command": "python",
      "args": ["-m", "nodemaven_mcp"],
      "env": {
        "NODEMAVEN_API_KEY": "your-api-key",
        "NODEMAVEN_PROXY_USERNAME": "your-proxy-username",
        "NODEMAVEN_PROXY_PASSWORD": "your-proxy-password"
      }
    }
  }
}

A local .env in the working directory also works - see .env.example. Environment variables always win over the file.

On Windows, give the absolute path to python.exe rather than bare python. If Python came from the Microsoft Store, the python on your PATH is an app execution alias that MCP clients cannot spawn, and the server silently never appears. python -c "import sys; print(sys.executable)" prints the path to use.

Use it

Three things worth asking your agent, once it is connected:

Check what a site sees

"Am I actually coming out of Germany? Use a Vodafone IP if you can."

The agent calls nodemaven_check_proxy(country="de", isp="vodafone") and reports the exit IP, city and latency. Useful as a smoke test before a long run.

Read geo-restricted content

"Fetch this page as a US shopper in New York and tell me the price."

nodemaven_fetch(url=..., country="us", city="new york") returns readable text, truncated to 200 KB by default so it does not flood the context.

Keep one identity across a flow

"Log into the demo account and walk through checkout, same IP the whole time."

Pass the same session_id (4-10 alphanumerics) on every call and NodeMaven pins the exit IP; drop it and the IP rotates per request.

Targeting spellings matter. nodemaven_list_locations(level="cities", country="de") gives the exact values NodeMaven accepts, which is the difference between a working pool and an empty one.

See what it actually does

A tool call is easy to trust and hard to verify. examples/traffic_dashboard.py runs a local forward proxy with a live dashboard, so you can point the server at it and watch every hop it makes:

python examples/traffic_dashboard.py     # proxy on :8080, dashboard on :8099
NODEMAVEN_PROXY_HOST=127.0.0.1
NODEMAVEN_HTTP_PORT=8080

Dashboard showing proxy hops with decoded targeting

Each row is a real network request. The route column is decoded from the proxy username, which is exactly the string NodeMaven uses to choose the exit IP - so you can confirm that country="de", city="Munich" in a tool call really did leave your machine as DE / MUNICH, and that a session_id stayed pinned across calls.

The dashboard is a development aid: it accepts any credentials and does not encrypt anything. Do not put it on a network you share.

Design notes

Passwords stay masked. build_proxy_url returns *** in place of the password unless the caller passes reveal_credentials=true. Transcripts get shared, pasted into issues and fed back into models; a proxy password should not ride along by default.

Errors are written for an agent, not a log file. A refused connection says that an over-narrow city or ISP filter is the usual cause and suggests widening it. A 401 names the environment variable to check. An agent that can read the error can retry correctly on the first attempt.

Targeting is pure and tested. NodeMaven encodes location in the proxy username:

acct-country-us-region-california-city-los_angeles-isp-t_mobile_usa-sid-ab12cd-filter-medium

Building that string - normalizing "Los Angeles" to los_angeles, rejecting a session id that would silently disable stickiness, validating the port against the range for the chosen protocol - is pure logic, so it is covered by tests that never touch the network.

No parser dependency. HTML-to-text runs on html.parser from the standard library. The dependency list is mcp, httpx and pydantic.

Development

pip install -e ".[dev]"
pytest -q          # 60 tests, no network, no credentials needed
ruff check .

CI runs the suite on Python 3.10, 3.11 and 3.12.

Contributions welcome - see CONTRIBUTING.md.

License

MIT

Available Tools

5 tools
nodemaven_build_proxy_urlA
Read-onlyIdempotent

Build a NodeMaven proxy URL with geo targeting encoded in the username.

Use this to hand a ready connection string to another tool - curl, Playwright, Scrapy, requests - instead of guessing NodeMaven's username syntax. No network call is made. To verify the IP actually works, use nodemaven_check_proxy.

Returns: str: Markdown or JSON with the schema: { "proxy_url": str, # e.g. "http://user-country-us-sid-ab12:***@gate.nodemaven.com:8080" "username": str, # targeting username "host": str, "port": int, "protocol": str, "password_masked": bool } On failure: "Error: "

Examples: - "give me a US proxy string for curl" -> country='us', reveal_credentials=true - "same IP for the whole login flow" -> session_id='ab12cd' - Don't use when: you want the page content (use nodemaven_fetch instead)

Inputs: country (required), isp, city, port, +7 more. Returns: result

nodemaven_check_proxyA
Read-only

Send one request through the proxy and report the exit IP, its geo and latency.

Use this before a scraping run to confirm the targeting resolves to a real pool and that the exit IP is where you expect. Over-narrow targeting (a rare city plus an ISP filter) is the usual reason a connection fails.

Returns: str: Markdown or JSON with the schema: { "exit_ip": str, # e.g. "104.28.51.7" "country": str, # e.g. "US" "region": str, "city": str, "org": str, "latency_ms": int, "proxy": str, # password-masked proxy URL "session_id_used": bool } On failure: "Error: "

Examples: - "am I really coming out of Germany?" -> country='de' - "does this sticky session hold?" -> session_id='ab12cd', call twice - Don't use when: you need the catalogue of available cities (use nodemaven_list_locations)

Inputs: country (required), isp, city, port, +6 more. Returns: result

nodemaven_fetchA
Read-only

Fetch a URL through a NodeMaven residential or mobile IP and return its content.

Use this when a page is geo-restricted or blocks datacenter traffic. HTML is converted to readable text by default so it does not flood the context; set as_text=false when the markup itself matters.

Returns: str: Markdown or JSON with the schema: { "url": str, # final URL after redirects "status_code": int, "content_type": str, "title": str | None, # HTML when available "latency_ms": int, "truncated": bool, "bytes": int, "body": str, "proxy": str # password-masked proxy URL } On failure: "Error: "

Examples: - "read this page as a German visitor" -> url=..., country='de' - "check the price shown to US shoppers" -> url=..., country='us', city='new york' - Don't use when: the site is reachable without a proxy (use a plain fetch)

Inputs: url (required), country (required), isp, city, +9 more. Returns: result

nodemaven_get_usageA
Read-onlyIdempotent

Report account usage: traffic consumed, request counts or per-domain breakdown.

Use this to check remaining traffic before a large run, or to attribute spend to the domains that caused it.

Returns: str: Markdown or JSON with the same pagination envelope as nodemaven_list_locations, where items are usage records. On failure: "Error: "

Examples: - "how much traffic have I burned?" -> kind='data' - "which domains cost me the most?" -> kind='domains'

Requires NODEMAVEN_API_KEY.

Inputs: kind, limit, offset, response_format. Returns: result

nodemaven_list_locationsA
Read-onlyIdempotent

List the countries, regions, cities, ISPs or zip codes available for targeting.

Use this to discover exact spellings before targeting - guessing a city name is the most common reason a proxy connection returns an empty pool.

Returns: str: Markdown or JSON with the schema: { "total": int, "count": int, "offset": int, "limit": int, "has_more": bool, "next_offset": int | None, "items": [ { ... } ] # raw records as returned by NodeMaven } On failure: "Error: "

Examples: - "which countries can I target?" -> level='countries' - "list German cities" -> level='cities', country='de' - "which carriers exist in the US?" -> level='isps', country='us'

Requires NODEMAVEN_API_KEY.

Inputs: level, limit, offset, region, +2 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.8/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: building a proxy URL, testing a proxy, fetching content, listing targeting locations, and retrieving usage. No two tools overlap in purpose, and the descriptions reinforce the boundaries.

    Naming Consistency5/5

    All tool names follow a consistent `nodemaven_<verb>_<object>` pattern with lowercase snake_case. Verbs (build, check, fetch, list, get) are distinct and predictable, making the set easy to navigate.

    Tool Count5/5

    The server has 5 tools, which is well-scoped for a proxy management domain. Each tool earns its place, covering the essential operations without unnecessary bloat or redundancy.

    Completeness5/5

    The tool set covers the full proxy lifecycle: discover targeting options, construct a proxy URL, verify it works, fetch content through it, and monitor usage. There are no obvious dead ends or missing critical operations.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      A local MCP server that lets AI agents bypass bot detection, geo-restrictions, and JavaScript rendering challenges when scraping the web, backed by ScraperAPI's services
      28
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server giving AI agents controlled residential-proxy web access with optional browser rendering and structured extraction from 60+ sites.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server that lets AI agents use your real browser as an API, accessing any website with your login state, no keys or scrapers needed.
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that gives AI agents on-demand access to proxies from the world's leading and Russian/CIS proxy providers — through a single, unified interface.
      11
      MIT