nodemaven-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nodemaven-mcp Fetch this page as a US shopper in New York and tell me the price."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
nodemaven-mcp
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 msUnofficial, 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 |
| Builds a proxy URL with geo targeting encoded in the username, ready for curl, Playwright, Scrapy or requests | proxy creds |
| One request through the proxy: exit IP, geo, ISP, latency | proxy creds |
| Fetches a URL through the proxy, HTML converted to readable text | proxy creds |
| Countries, regions, cities, ISPs, zip codes available for targeting | API key |
| 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_mcpClaude 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 :8099NODEMAVEN_PROXY_HOST=127.0.0.1
NODEMAVEN_HTTP_PORT=8080
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-mediumBuilding 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 toolsnodemaven_build_proxy_urlARead-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_proxyARead-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_fetchARead-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_usageARead-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_locationsARead-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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Web search API and MCP server for developers building AI agents.
AI tool directory MCP server, live since July 2026. Tools, agents, models, companies, services.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Related MCP Servers
AlicenseAqualityCmaintenanceA local MCP server that lets AI agents bypass bot detection, geo-restrictions, and JavaScript rendering challenges when scraping the web, backed by ScraperAPI's services285MIT- AlicenseNot gradedqualityDmaintenanceMCP server giving AI agents controlled residential-proxy web access with optional browser rendering and structured extraction from 60+ sites.1MIT
- AlicenseNot gradedqualityBmaintenanceMCP server that lets AI agents use your real browser as an API, accessing any website with your login state, no keys or scrapers needed.1MIT
- AlicenseAqualityDmaintenanceAn 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.11MIT