Proxy4agents Mcp

io.github.NovadaLabs由 GitHub 帳號 NovadaLabs 發布v1.7.0更新於 Oct 25, 2026

Residential proxy MCP for AI agents — geo-targeting, sticky sessions, anti-bot bypass.

已驗證STDIO僅桌面網頁搜尋與抓取瀏覽器自動化

服務詳細資訊

識別碼: io.github.NovadaLabs/proxy4agents-mcp
傳輸: STDIO
執行環境: Desktop only
信任: Verified
發布於: Sep 16, 2026

安全提示

MCP 服務會接收對話中的工具呼叫請求，並可能執行外部操作。啟用前請先了解該服務能做什麼，並只授予它所需的權限。

註冊中心已驗證此條目所屬的 GitHub 帳號 NovadaLabs。這並不表明該帳號就是產品方。

SourceWeft 的檢查只涵蓋條目是否完整、端點是否回應；不審查伺服器的程式碼，也不審查其工具的行為。

在 README 中新增徽章

向讀者展示該 MCP 服務已收錄於 SourceWeft，徽章連結到本頁。

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.NovadaLabs%2Fproxy4agents-mcp.svg)](https://sourceweft.com/mcp/io.github.NovadaLabs%2Fproxy4agents-mcp?utm_source=readme&utm_medium=badge)

概覽

AI 產生的概覽

本機 MCP 伺服器，讓助理透過住宅代理抓取網頁，支援地理定向、網站爬取、搜尋、JS 渲染與一次性研究。

可以做什麼: 透過住宅代理抓取單一或批次 URL，可依國家、城市定向，並用黏性工作階段在多次呼叫間維持同一個 IP，還可檢查代理網路狀態與版本。從頁面擷取結構化欄位，支援啟發式欄位或由助理依 schema 擷取，並可對網站做連結盤點或遞迴爬取以找出網址。透過 Novada Scraper API 執行 Google 搜尋，以 JSON 回傳標題、網址與摘要。用真實 Chromium 渲染依賴 JavaScript 的頁面，並執行一次性研究：搜尋、抓取主要來源並回傳含預覽的結果。
適用情境: 適合助理需要讀取會阻擋一般請求的頁面、查看特定國家或城市呈現的內容、在多頁流程中維持固定 IP，或一次蒐集並閱讀某主題多個來源的情況。
執行需求: 透過 npx 在本機執行（需要 Node.js）。多數工具需要代理憑證 NOVADA_PROXY_USER 與 NOVADA_PROXY_PASS；NOVADA_API_KEY 啟用搜尋與研究，NOVADA_BROWSER_WS 啟用渲染。也可用 BRIGHTDATA_USER/BRIGHTDATA_PASS、SMARTPROXY_USER/SMARTPROXY_PASS、OXYLABS_USER/OXYLABS_PASS 或 PROXY_URL 設定其他供應商。需要網路存取。

安裝前請注意

需要付費的第三方代理與 API 帳號；呼叫會消耗代理額度，渲染每次約消耗五個額度，一般抓取則為一個。用戶端設定會保存多個機密類環境變數，包括代理密碼與 API 金鑰。抓取內容會經由代理供應商轉送，其可看到目標網址。爬取與批次抓取會產生大量請求與費用，應遵守目標網站的條款與頻率限制。

安裝

在 SourceWeft 中

開啟儀表板中的 Proxy4agents Mcp，將其新增到工作區。
為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照儲存庫中的啟動說明。

README

Novada Proxy

The agent-first residential proxy MCP — works with any provider.

Route any HTTP request through 2M+ real home devices — Android phones, Windows PCs, Macs — to bypass anti-bot systems, geo-target by country or city, and maintain sticky sessions across multi-step workflows. Powered by Novada.

[npm version] [npm downloads] [License: MIT] [CI] [Node.js]

[10 tools] [5 prompts] [5 resources] [430 tests] [5 providers]

[LobeHub MCP] [LobeHub MCP Full] [Smithery] [MCP Registry]

[English] [中文文档]

Why · Install · Tools · Prompts · Resources · Providers · Agent-First

Works with Claude Code, Cursor, Windsurf, Cline, Continue, and any MCP-compatible AI agent.

[!TIP] Free tier available — sign up at novada.com, no credit card required. Get free access to Scraper API, Web Unblocker, and residential proxies to start building immediately.

Getting Started

[Step 1] [Step 2] [Step 3]

For Humans

Create a free account at novada.com — no credit card required
Get your credentials at Dashboard → Residential Proxies → Endpoint Generator — copy your username and password
Install and run:

bash

# Claude Codeclaude mcp add novada-proxy-mcp \  -e NOVADA_PROXY_USER=your_username \  -e NOVADA_PROXY_PASS=your_password \  -- npx -y novada-proxy-mcp
# Or use the CLI directlynpx novada-proxy-mcp statusnpx novada-proxy fetch https://example.com

# Claude Codeclaude mcp add novada-proxy-mcp \  -e NOVADA_PROXY_USER=your_username \  -e NOVADA_PROXY_PASS=your_password \  -- npx -y novada-proxy-mcp
# Or use the CLI directlynpx novada-proxy-mcp statusnpx novada-proxy fetch https://example.com

For Agents

[!NOTE] Agents: Tell your human to complete steps 1-2 above. Once credentials are set as environment variables, all 10 tools are available immediately. No API key rotation, no token refresh — proxy credentials are persistent.

Required env vars:  NOVADA_PROXY_USER   — from novada.com dashboard  NOVADA_PROXY_PASS   — from novada.com dashboard
Optional (for extra features):  NOVADA_API_KEY      — enables novada_proxy_search (Google search)  NOVADA_BROWSER_WS   — enables novada_proxy_render (JS rendering)  NOVADA_PROXY_ZONE   — "res" (default), "isp", or "dcp"

Required env vars:  NOVADA_PROXY_USER   — from novada.com dashboard  NOVADA_PROXY_PASS   — from novada.com dashboard
Optional (for extra features):  NOVADA_API_KEY      — enables novada_proxy_search (Google search)  NOVADA_BROWSER_WS   — enables novada_proxy_render (JS rendering)  NOVADA_PROXY_ZONE   — "res" (default), "isp", or "dcp"

Need help? Contact [email protected]

Why Novada Proxy

AI agents get blocked on 60–70% of commercial websites. Standard HTTP requests are detected and rejected by Cloudflare, Akamai, DataDome, and PerimeterX. Novada Proxy routes your agent through real residential IPs — indistinguishable from a human browser.

Problem	Solution
Amazon, LinkedIn, Cloudflare block your agent	2M+ residential IPs from real home devices
Bot challenges return 403 / CAPTCHA	Real device fingerprints bypass detection
JS-rendered pages return blank content	`novada_proxy_render` runs real Chromium
Geo-restricted or localized content	195+ countries, city-level targeting
Multi-step workflows need the same IP	Sticky sessions — consistent IP across calls
Scraping 10+ URLs wastes time	`novada_proxy_batch_fetch` — concurrent, parallel
Need structured fields, not raw HTML	`novada_proxy_extract` — title, price, rating, etc.
Finding URLs before scraping	`novada_proxy_map` — discover all internal links
Need clean search results	`novada_proxy_search` — Google results as JSON

10 Tools at a Glance

Tool	What It Does	Requires
`novada_proxy_fetch`	Fetch any URL through residential proxy	Proxy credentials
`novada_proxy_batch_fetch`	Fetch 2–20 URLs concurrently (up to 5x parallel)	Proxy credentials
`novada_proxy_extract`	Extract structured fields — heuristic mode (fields) or LLM mode (schema)	Proxy credentials
`novada_proxy_map`	Crawl a URL and return all internal links as JSON array	Proxy credentials
`novada_proxy_crawl`	Recursively crawl a site (BFS, depth 1-5) with URL discovery	Proxy credentials
`novada_proxy_session`	Sticky session — same IP across every call	Proxy credentials
`novada_proxy_search`	Google search -> structured JSON (title, url, snippet)	`NOVADA_API_KEY`
`novada_proxy_render`	Render JS-heavy pages with real Chromium [BETA]	`NOVADA_BROWSER_WS`
`novada_proxy_research`	One-shot deep research — search + fetch + synthesize	`NOVADA_API_KEY` + Proxy
`novada_proxy_status`	Check proxy network health + version	(none)

Quick Decision Guide

I want to...	Use this tool
Fetch a single URL	`novada_proxy_fetch`
Fetch 2–20 URLs at once	`novada_proxy_batch_fetch`
Extract specific fields (title, price...)	`novada_proxy_extract` with `fields`
Extract ANY field via schema	`novada_proxy_extract` with `schema`
Find all links on a page	`novada_proxy_map`
Crawl an entire site	`novada_proxy_crawl`
Research a topic	`novada_proxy_research`
Search Google	`novada_proxy_search`
Render a JS-heavy page	`novada_proxy_render`
Keep same IP across calls	`novada_proxy_session`
Check if proxy works	`novada_proxy_status`

When To Use Which Tool

Goal: "Scrape a single URL"  └─ Static HTML page?          → novada_proxy_fetch  └─ Need specific fields?      → novada_proxy_extract (fields or schema mode)  └─ React/Vue SPA / blank page? → novada_proxy_render
Goal: "Scrape multiple URLs"  └─ You have the URLs already  → novada_proxy_batch_fetch  └─ You need links from one page → novada_proxy_map → novada_proxy_batch_fetch  └─ You need to crawl a whole site → novada_proxy_crawl → novada_proxy_batch_fetch
Goal: "Research a topic"        → novada_proxy_research (search + fetch + findings in one call)
Goal: "Search the web"          → novada_proxy_search → novada_proxy_batch_fetch
Goal: "Login + multi-page flow" → novada_proxy_session (same session_id)
Goal: "Check if proxy works"    → novada_proxy_status

Goal: "Scrape a single URL"  └─ Static HTML page?          → novada_proxy_fetch  └─ Need specific fields?      → novada_proxy_extract (fields or schema mode)  └─ React/Vue SPA / blank page? → novada_proxy_render
Goal: "Scrape multiple URLs"  └─ You have the URLs already  → novada_proxy_batch_fetch  └─ You need links from one page → novada_proxy_map → novada_proxy_batch_fetch  └─ You need to crawl a whole site → novada_proxy_crawl → novada_proxy_batch_fetch
Goal: "Research a topic"        → novada_proxy_research (search + fetch + findings in one call)
Goal: "Search the web"          → novada_proxy_search → novada_proxy_batch_fetch
Goal: "Login + multi-page flow" → novada_proxy_session (same session_id)
Goal: "Check if proxy works"    → novada_proxy_status

5 Prompts

Pre-built agent workflows that chain multiple tools together. Call these from any MCP client to execute common patterns in one step.

Prompt	Description	Key Arguments
`fetch_url`	Fetch a URL through residential proxy with anti-bot bypass	`url`, `country`, `format`
`research_topic`	Search + batch read workflow — find and read top pages on a topic	`query`, `num_results`, `country`
`extract_product`	Extract structured product data from any e-commerce URL	`url`, `fields`
`crawl_site`	Discover all pages on a site, then fetch them in parallel	`url`, `limit`, `country`
`troubleshoot`	Step-by-step proxy diagnosis when things go wrong	`error_message`

[!NOTE] Prompts orchestrate multi-tool workflows automatically. For example, research_topic runs novada_proxy_search then novada_proxy_batch_fetch in sequence — the agent doesn't need to figure out the pipeline.

5 Resources

Always-accessible reference data that agents can read at any time, without making proxy calls.

Resource URI	Description
`proxy://countries`	Complete list of 195+ country codes with city-level targeting
`proxy://error-codes`	All typed error codes with recovery instructions
`proxy://workflows`	Common agent workflow patterns (crawl, research, monitoring)
`proxy://supported-fields`	All fields `novada_proxy_extract` can extract with strategies
`proxy://cost-guide`	Credits per tool, caching behavior, cost optimization tips

Quick Install

Core — fetch any URL through residential proxy:

bash

claude mcp add novada-proxy-mcp \  -e NOVADA_PROXY_USER=your_username \  -e NOVADA_PROXY_PASS=your_password \  -- npx -y novada-proxy-mcp

claude mcp add novada-proxy-mcp \  -e NOVADA_PROXY_USER=your_username \  -e NOVADA_PROXY_PASS=your_password \  -- npx -y novada-proxy-mcp

Search only:

All tools (proxy + search + browser render):

bash

claude mcp add novada-proxy-mcp \  -e NOVADA_PROXY_USER=your_username \  -e NOVADA_PROXY_PASS=your_password \  -e NOVADA_API_KEY=your_key \  -e NOVADA_BROWSER_WS=your_browser_ws_url \  -- npx -y novada-proxy-mcp

claude mcp add novada-proxy-mcp \  -e NOVADA_PROXY_USER=your_username \  -e NOVADA_PROXY_PASS=your_password \  -e NOVADA_API_KEY=your_key \  -e NOVADA_BROWSER_WS=your_browser_ws_url \  -- npx -y novada-proxy-mcp

Cursor / Windsurf / Cline — add to MCP config:

json

{  "mcpServers": {    "novada-proxy-mcp": {      "command": "npx",      "args": ["-y", "novada-proxy-mcp"],      "env": {        "NOVADA_PROXY_USER": "your_username",        "NOVADA_PROXY_PASS": "your_password"      }    }  }}

{  "mcpServers": {    "novada-proxy-mcp": {      "command": "npx",      "args": ["-y", "novada-proxy-mcp"],      "env": {        "NOVADA_PROXY_USER": "your_username",        "NOVADA_PROXY_PASS": "your_password"      }    }  }}

Get credentials: novada.com -> Dashboard -> Residential Proxies -> Endpoint Generator

Providers

Novada Proxy works with any HTTP proxy provider. Novada is the built-in default with the deepest integration.

Priority: Novada -> BrightData -> Smartproxy -> Oxylabs -> Generic. First configured provider wins.

Feature	Novada	BrightData	Smartproxy	Oxylabs	Generic HTTP
Auto country targeting	✓	✓	✓	✓	manual
Auto city targeting	✓	✓	✓	✓	manual
Sticky sessions	✓	✓	✓	✓	manual
Built-in search API	✓	—	—	—	—
Browser API (JS render)	✓	—	—	—	—

BrightData setup

bash

claude mcp add novada-proxy-mcp \  -e BRIGHTDATA_USER="brd-customer-abc123-zone-residential" \  -e BRIGHTDATA_PASS=your_password \  -- npx -y novada-proxy-mcp

claude mcp add novada-proxy-mcp \  -e BRIGHTDATA_USER="brd-customer-abc123-zone-residential" \  -e BRIGHTDATA_PASS=your_password \  -- npx -y novada-proxy-mcp

BRIGHTDATA_USER is your full username including zone. Optional: BRIGHTDATA_HOST, BRIGHTDATA_PORT (default zproxy.lum-superproxy.io:22225).

Smartproxy setup

bash

claude mcp add novada-proxy-mcp \  -e SMARTPROXY_USER=your_username \  -e SMARTPROXY_PASS=your_password \  -- npx -y novada-proxy-mcp

claude mcp add novada-proxy-mcp \  -e SMARTPROXY_USER=your_username \  -e SMARTPROXY_PASS=your_password \  -- npx -y novada-proxy-mcp

Optional: SMARTPROXY_HOST, SMARTPROXY_PORT (default gate.smartproxy.com:10001).

Oxylabs setup

bash

claude mcp add novada-proxy-mcp \  -e OXYLABS_USER=your_username \  -e OXYLABS_PASS=your_password \  -- npx -y novada-proxy-mcp

claude mcp add novada-proxy-mcp \  -e OXYLABS_USER=your_username \  -e OXYLABS_PASS=your_password \  -- npx -y novada-proxy-mcp

Optional: OXYLABS_HOST, OXYLABS_PORT (default pr.oxylabs.io:7777).

Generic HTTP proxy (IPRoyal, any provider)

bash

claude mcp add novada-proxy-mcp \  -e PROXY_URL="http://username:[email protected]:12321" \  -- npx -y novada-proxy-mcp

claude mcp add novada-proxy-mcp \  -e PROXY_URL="http://username:[email protected]:12321" \  -- npx -y novada-proxy-mcp

country, city, session_id params are ignored with Generic — encode targeting directly in your proxy URL.

Agent-First Design

[!NOTE] Novada Proxy is the only proxy MCP designed specifically for autonomous AI agents. Every response, error, and description is optimized for machine consumption.

Feature	What It Means
`agent_instruction` in errors	Every error tells the agent exactly what to do next
Decision trees in descriptions	WHEN TO USE / USE INSTEAD guides in every tool
`cache_hit` metadata	Agent knows when 0 credits were used (cached response)
`credits_estimated` per call	Cost tracking built into every response
Typed error codes	Machine-readable: `BOT_DETECTION_SUSPECTED`, `PAGE_NOT_FOUND`, etc.
5 workflow prompts	Pre-built agent workflows: research, crawl, extract, diagnose
5 reference resources	Countries, error codes, cost guide — always accessible

Tools

`novada_proxy_fetch`

Fetch any URL through a residential proxy. Returns structured JSON with content, status code, and metadata. Auto-retry on network errors. Caches repeated calls (default 300s TTL — meta.cache_hit: true means no proxy credit used).

Parameter	Type	Default	Description
`url`	string	required	Target URL (`http://` or `https://`)
`country`	string	—	2-letter ISO code: `US`, `DE`, `JP`, `GB`, `BR`... (195+ options)
`city`	string	—	City: `newyork`, `london`, `tokyo`, `paris`, `berlin`...
`session_id`	string	—	Reuse same ID for same IP across calls (no hyphens, max 64 chars)
`format`	string	`markdown`	`markdown` strips HTML / `raw` returns full HTML
`timeout`	number	`60`	Timeout in seconds (1–120)

Response:

json

{  "ok": true,  "tool": "novada_proxy_fetch",  "data": { "url": "...", "status_code": 200, "content": "...", "size_bytes": 34000 },  "meta": { "latency_ms": 1800, "cache_hit": false, "quota": { "credits_estimated": 1 } }}

{  "ok": true,  "tool": "novada_proxy_fetch",  "data": { "url": "...", "status_code": 200, "content": "...", "size_bytes": 34000 },  "meta": { "latency_ms": 1800, "cache_hit": false, "quota": { "credits_estimated": 1 } }}

`novada_proxy_batch_fetch`

Fetch 2–20 URLs concurrently through residential proxy. Up to 5x faster than sequential fetches. Per-URL errors are captured individually — the batch itself succeeds even if some URLs fail. Reuses response cache for URLs already fetched.

Parameter	Type	Default	Description
`urls`	string[]	required	2–20 URLs to fetch
`concurrency`	number	`3`	Parallel requests (1–5)
`country`	string	—	Same country for all URLs
`format`	string	`markdown`	`markdown` or `raw`
`timeout`	number	`60`	Per-URL timeout in seconds

Response:

json

{  "ok": true,  "tool": "novada_proxy_batch_fetch",  "data": {    "requested": 3,    "succeeded": 3,    "failed": 0,    "results": [      { "url": "https://...", "ok": true, "content": "...", "cache_hit": false, "latency_ms": 1200 },      { "url": "https://...", "ok": true, "content": "...", "cache_hit": true,  "latency_ms": 0 },      { "url": "https://...", "ok": false, "error": { "code": "TLS_ERROR", "message": "..." } }    ]  },  "meta": { "latency_ms": 4100, "quota": { "credits_estimated": 3 } }}

{  "ok": true,  "tool": "novada_proxy_batch_fetch",  "data": {    "requested": 3,    "succeeded": 3,    "failed": 0,    "results": [      { "url": "https://...", "ok": true, "content": "...", "cache_hit": false, "latency_ms": 1200 },      { "url": "https://...", "ok": true, "content": "...", "cache_hit": true,  "latency_ms": 0 },      { "url": "https://...", "ok": false, "error": { "code": "TLS_ERROR", "message": "..." } }    ]  },  "meta": { "latency_ms": 4100, "quota": { "credits_estimated": 3 } }}

`novada_proxy_extract`

Extract structured fields from any URL using heuristic pattern matching (meta tags, Open Graph, JSON-LD, Schema.org). Lightweight — no LLM needed. Set render_fallback: true to automatically retry via real Chromium if the proxy fetch fails.

Parameter	Type	Default	Description
`url`	string	required	Target URL
`fields`	string[]	required	Fields to extract: `title`, `price`, `description`, `rating`, `image`, `author`, `date`...
`render_fallback`	boolean	`false`	Auto-retry via `novada_proxy_render` on TLS/bot block
`country`	string	—	Geo-target the fetch
`timeout`	number	`60`	Timeout in seconds

Response:

json

{  "ok": true,  "tool": "novada_proxy_extract",  "data": {    "url": "https://books.toscrape.com/...",    "fields": { "title": "A Light in the Attic", "price": "£51.77", "description": null },    "extracted_via": "proxy_fetch"  },  "meta": { "latency_ms": 2100, "quota": { "credits_estimated": 1 } }}

{  "ok": true,  "tool": "novada_proxy_extract",  "data": {    "url": "https://books.toscrape.com/...",    "fields": { "title": "A Light in the Attic", "price": "£51.77", "description": null },    "extracted_via": "proxy_fetch"  },  "meta": { "latency_ms": 2100, "quota": { "credits_estimated": 1 } }}

`novada_proxy_map`

Crawl a URL and return all internal links as a structured JSON array. Use as the discovery step before novada_proxy_batch_fetch to crawl an entire site without guessing URLs.

Parameter	Type	Default	Description
`url`	string	required	Starting URL to crawl
`limit`	number	`50`	Max URLs to return (10–200)
`include_external`	boolean	`false`	Include off-domain links
`country`	string	—	Geo-target the fetch
`timeout`	number	`60`	Timeout in seconds

Response:

json

{  "ok": true,  "tool": "novada_proxy_map",  "data": {    "domain": "books.toscrape.com",    "internal_url_count": 20,    "internal_urls": ["https://books.toscrape.com/catalogue/...", "..."],    "sitemap_hint": "https://books.toscrape.com/sitemap.xml (check manually)"  },  "meta": { "latency_ms": 3800, "quota": { "credits_estimated": 1 } }}

{  "ok": true,  "tool": "novada_proxy_map",  "data": {    "domain": "books.toscrape.com",    "internal_url_count": 20,    "internal_urls": ["https://books.toscrape.com/catalogue/...", "..."],    "sitemap_hint": "https://books.toscrape.com/sitemap.xml (check manually)"  },  "meta": { "latency_ms": 3800, "quota": { "credits_estimated": 1 } }}

`novada_proxy_session`

Sticky session fetch — every call with the same session_id uses the same residential IP. Essential for login flows, paginated scraping, and price monitoring. Supports verify_sticky: true to confirm IP consistency before relying on it.

Parameter	Type	Default	Description
`session_id`	string	required	Unique ID — reuse to keep same IP (no hyphens, max 64 chars)
`url`	string	required	Target URL
`country`	string	—	2-letter country code
`city`	string	—	City-level targeting
`verify_sticky`	boolean	`false`	Make 3 proxy calls to confirm IP consistency (adds ~15–25s)
`format`	string	`markdown`	`markdown` or `raw`
`timeout`	number	`60`	Timeout in seconds

`novada_proxy_search`

Structured Google search via Novada Scraper API. Returns titles, URLs, and snippets as clean JSON — no HTML parsing needed.

`novada_proxy_render` [BETA]

Render JavaScript-heavy pages using Novada's Browser API (real Chromium, full JS execution). Use for SPAs, React/Vue apps, and pages that return blank with a standard HTTP fetch.

Requires: NOVADA_BROWSER_WS — copy the Puppeteer URL from Dashboard -> Browser API -> Playground

Parameter	Type	Default	Description
`url`	string	required	Target URL
`format`	string	`markdown`	`markdown` / `html` / `text`
`wait_for`	string	—	CSS selector to wait for before extracting (e.g. `.product-title`)
`timeout`	number	`60`	Timeout in seconds (5–120)

Costs ~5 proxy credits per call vs 1 for novada_proxy_fetch. Use novada_proxy_extract with render_fallback: true for automatic escalation when needed.

`novada_proxy_crawl`

Recursively crawl a website via BFS traversal. Starts from a URL, discovers links at each depth level, and returns the full URL tree with metadata.

Parameter	Type	Default	Description
`url`	string	required	Starting URL to crawl
`depth`	number	`2`	BFS depth (1–5)
`limit`	number	`50`	Max pages to crawl (10–200)
`include_content`	boolean	`false`	Also return page content for each URL
`country`	string	—	Geo-target all fetches
`format`	string	`markdown`	Content format when `include_content: true`
`timeout`	number	`60`	Per-page timeout in seconds

When to use: Full-site scraping, sitemap generation, content indexing — when you need MORE than a single page.

Use novada_proxy_map instead if: You only need links from ONE page (one level deep). Map is faster and cheaper for single-page link discovery.

Chain with: novada_proxy_batch_fetch to scrape specific pages from the URL tree.

Example:

Response: data.pages[] (url, depth, status_code, total_links), data.urls[] (flat array for chaining into novada_proxy_batch_fetch)

`novada_proxy_research`

One-shot research tool — searches the web, fetches top results, and returns structured findings with source previews. The agent can analyze the findings for deeper synthesis.

Parameter	Type	Default	Description
`query`	string	required	Research question or topic
`depth`	string	`"standard"`	`"quick"` (3 sources), `"standard"` (5 sources), `"deep"` (10 sources)
`country`	string	—	Localize search results
`timeout`	number	`60`	Timeout in seconds

Requires: NOVADA_API_KEY (for Google search) + Proxy credentials (for fetching sources)

When to use: Research questions, topic investigation, competitive analysis, fact-finding — when you need content from multiple sources in one call.

Use novada_proxy_search instead if: You just need search result URLs, not full page content.

Chain with: novada_proxy_fetch on specific urls[] for deeper reading of individual sources.

Note: findings_summary is a concatenated preview of sources — your agent should analyze findings[] for actual synthesis.

Example:

Response: data.findings[] (title, url, snippet, content_preview), data.urls[] (for chaining), data.findings_summary

`novada_proxy_extract` — Schema Mode

In addition to fields (heuristic extraction), novada_proxy_extract supports a schema parameter for extracting any arbitrary field via your agent's LLM — zero additional API cost.

Schema Mode (LLM Extraction)

Pass schema instead of fields for arbitrary field extraction. The tool returns cleaned page content + an extraction prompt — your agent does the extraction (zero additional API cost).

Parameter	Type	Default	Description
`url`	string	required	Target URL
`schema`	object	—	Keys = field names, values = field descriptions. Use instead of `fields`.
`render_fallback`	boolean	`false`	Auto-retry via `novada_proxy_render` on TLS/bot block
`country`	string	—	Geo-target the fetch
`timeout`	number	`60`	Timeout in seconds

Example:

json

{  "url": "https://example.com/product",  "schema": {    "product_name": "The full product name",    "price": "Current price with currency",    "warranty": "Warranty terms and duration",    "return_policy": "Return policy summary"  }}

{  "url": "https://example.com/product",  "schema": {    "product_name": "The full product name",    "price": "Current price with currency",    "warranty": "Warranty terms and duration",    "return_policy": "Return policy summary"  }}

Response: data.mode = "llm_extract", data.content (cleaned markdown), data.extraction_prompt (instructions for your agent to follow and extract the fields)

Security: Schema keys must be alphanumeric/underscore (a-z, 0-9, _), max 50 chars. Values max 200 chars.

`novada_proxy_status`

Check proxy network connectivity and version. Makes a live proxy call to verify the connection is working. No credentials required.

Agent Workflows

Site crawl pipeline (map -> batch)

# Agent task: "Read all products on this catalogue"1. novada_proxy_map(url="https://books.toscrape.com", limit=50)   → returns 20–50 internal URLs in 4s, 1 credit
2. novada_proxy_batch_fetch(urls=[...20 URLs], concurrency=5)   → fetches all 20 pages in parallel, ~4s wall time, 20 credits   (vs ~60s sequential = 15x speedup)

# Agent task: "Read all products on this catalogue"1. novada_proxy_map(url="https://books.toscrape.com", limit=50)   → returns 20–50 internal URLs in 4s, 1 credit
2. novada_proxy_batch_fetch(urls=[...20 URLs], concurrency=5)   → fetches all 20 pages in parallel, ~4s wall time, 20 credits   (vs ~60s sequential = 15x speedup)

Research pipeline (search -> batch)

# Agent task: "Find and read top 5 pages about X"1. novada_proxy_search(query="residential proxy MCP", num=5)   → structured JSON: titles, URLs, snippets
2. novada_proxy_batch_fetch(urls=[...5 URLs], format="markdown")   → full content of all 5 pages in parallel

# Agent task: "Find and read top 5 pages about X"1. novada_proxy_search(query="residential proxy MCP", num=5)   → structured JSON: titles, URLs, snippets
2. novada_proxy_batch_fetch(urls=[...5 URLs], format="markdown")   → full content of all 5 pages in parallel

Sticky session — login + multi-page scrape

# Same IP across all callsnovada_proxy_session(session_id="job_001", url="https://example.com/login")novada_proxy_session(session_id="job_001", url="https://example.com/dashboard")novada_proxy_session(session_id="job_001", url="https://example.com/data/page/1")novada_proxy_session(session_id="job_001", url="https://example.com/data/page/2")

# Same IP across all callsnovada_proxy_session(session_id="job_001", url="https://example.com/login")novada_proxy_session(session_id="job_001", url="https://example.com/dashboard")novada_proxy_session(session_id="job_001", url="https://example.com/data/page/1")novada_proxy_session(session_id="job_001", url="https://example.com/data/page/2")

Price monitoring — same product, three markets

novada_proxy_fetch(url="https://amazon.com/dp/B0BSHF7WHW", country="US")novada_proxy_fetch(url="https://amazon.com/dp/B0BSHF7WHW", country="DE")novada_proxy_fetch(url="https://amazon.com/dp/B0BSHF7WHW", country="JP")# Second call per URL is a cache hit (0ms, 0 credits) if within 300s TTL

novada_proxy_fetch(url="https://amazon.com/dp/B0BSHF7WHW", country="US")novada_proxy_fetch(url="https://amazon.com/dp/B0BSHF7WHW", country="DE")novada_proxy_fetch(url="https://amazon.com/dp/B0BSHF7WHW", country="JP")# Second call per URL is a cache hit (0ms, 0 credits) if within 300s TTL

Extract structured data

# Agent task: "Get product details without parsing HTML"novada_proxy_extract(  url="https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",  fields=["title", "price", "description", "rating"],  render_fallback=true  # auto-retry via Chromium if proxy gets blocked)

# Agent task: "Get product details without parsing HTML"novada_proxy_extract(  url="https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",  fields=["title", "price", "description", "rating"],  render_fallback=true  # auto-retry via Chromium if proxy gets blocked)

Response Cache

All novada_proxy_fetch and novada_proxy_batch_fetch calls are cached in-process. Repeated fetches to the same URL within the TTL window consume zero proxy credits.

Behavior	Detail
Default TTL	300 seconds (5 minutes)
Cache key	`url + format + country`
Session bypass	`session_id` present -> never cached (sticky routing requires live calls)
Disable	Set `PROXY4AGENT_CACHE_TTL_SECONDS=0`
Max entries	200 (oldest evicted when full)

Reading cache status from response:

json

"meta": {  "cache_hit": true,          // served from cache — no proxy credit used  "cache_age_seconds": 12,    // seconds since the entry was stored  "latency_ms": 0             // ~0ms for cache hits}

"meta": {  "cache_hit": true,          // served from cache — no proxy credit used  "cache_age_seconds": 12,    // seconds since the entry was stored  "latency_ms": 0             // ~0ms for cache hits}

Typed Error Codes

Every error response includes a typed error.code, recoverable flag, and agent_instruction with the correct next step. Agents never need to parse error messages.

Code	Meaning	Recoverable	Agent Action
`BOT_DETECTION_SUSPECTED`	HTTP 4xx — target blocked the request	✓	Retry with `novada_proxy_render` or different `country`
`TLS_ERROR`	TLS/SSL connection failed through proxy	✓	Retry with a different `country` parameter
`TIMEOUT`	Request exceeded timeout limit	✓	Increase `timeout` or retry
`RATE_LIMITED`	HTTP 429 — too many requests	✓	Wait 5s and retry
`NETWORK_ERROR`	DNS failure — hostname not found	✗	Verify the URL is correct
`SESSION_STICKINESS_FAILED`	Same IP not maintained	✓	Retry `verify_sticky: true` to confirm
`INVALID_INPUT`	Bad parameter value	✗	Fix the parameter and retry
`PROVIDER_NOT_CONFIGURED`	Missing env vars	✗	Set credentials and restart MCP
`UNKNOWN_ERROR`	Unexpected error	✓	Check `novada_proxy_status`, retry

Error response format:

json

{  "ok": false,  "error": {    "code": "BOT_DETECTION_SUSPECTED",    "message": "HTTP 403 — request blocked by target",    "recoverable": true,    "agent_instruction": "Try novada_proxy_render (real browser). Or retry with a different country/session_id."  }}

{  "ok": false,  "error": {    "code": "BOT_DETECTION_SUSPECTED",    "message": "HTTP 403 — request blocked by target",    "recoverable": true,    "agent_instruction": "Try novada_proxy_render (real browser). Or retry with a different country/session_id."  }}

Geo Coverage

195+ countries including:

US GB DE FR JP CA AU BR IN KR SG NL IT ES MX RU PL SE NO DK FI CH AT BE PT CZ HU RO UA TR IL ZA NG EG AR CL CO PE VN TH ID MY PH TW HK NZ + 148 more

City-level targeting: newyork · losangeles · chicago · london · paris · berlin · tokyo · seoul · sydney · toronto · singapore · dubai · mumbai · saopaulo

Compatible With

Client	Install method
Claude Code	`claude mcp add novada-proxy-mcp -e ... -- npx -y novada-proxy-mcp`
Cursor	Settings -> MCP -> Add server -> `npx -y novada-proxy-mcp`
Windsurf	MCP config -> `npx -y novada-proxy-mcp`
Cline	MCP settings -> command: `npx`, args: `["-y", "novada-proxy-mcp"]`
Continue	`.continue/config.json` -> mcpServers
Smithery	smithery.ai/server/novada-proxy-mcp
Any MCP client	stdio transport / `npx -y novada-proxy-mcp`

Network

Confirmed Working

E-commerce: Amazon, eBay, Walmart, Etsy, Shopify stores
Professional: LinkedIn
Anti-bot protected: Cloudflare, Akamai, DataDome
News & content: HackerNews, Reddit, BBC, CNN, NYTimes
Tech: GitHub, Wikipedia, Stack Overflow, IMDB

Real-World Test Results

Tested across 3 Novada proxy types with 33 real-world tests (2026-04-28):

Proxy Type	Tests	Pass	Notes
Residential	11	9	Wikipedia, Shopify, HackerNews, geo-targeting work. Sticky sessions require endpoint config.
ISP	7	7	All tools work including sticky sessions (`session_verified: true`).
Datacenter	8	8	Fast, cost-effective. Anti-bot sites (Amazon, CNN) may block datacenter IPs — use residential for those.
Error handling	7	7	All error codes return structured JSON with `agent_instruction`.

Success rate: 94% (31/33 pass). Failures are proxy-type limitations (datacenter on anti-bot sites), not code bugs.

Proxy Type Guide

Use Case	Recommended Proxy	Why
Anti-bot sites (Amazon, LinkedIn, CNN)	Residential	Real home IPs, hardest to detect
Fast bulk scraping	Datacenter	Lowest latency, cheapest per GB
Sticky sessions (login flows)	ISP	6-hour sticky, stable IPs
General scraping	Any	All types handle most sites

Known Limitations

Limitation	Workaround
Datacenter IPs blocked on anti-bot sites	Use residential or ISP proxy type (`NOVADA_PROXY_ZONE=res`)
Proxy-side DNS errors surface as `TLS_ERROR`	Check if domain exists before retrying with different country
CLI is stateless (no cross-invocation cache)	Use MCP server for cache benefits, or re-fetch same URLs within one CLI batch
`novada_proxy_render` requires Browser API key	Set `NOVADA_BROWSER_WS` env var — get it from novada.com dashboard
Heuristic extraction misses a field	Use `schema` mode: pass `schema:{"field":"description"}` — returns cleaned content + extraction prompt for your agent to extract any field (zero-cost LLM extraction)

Feedback & Support

Email: [email protected]
GitHub Issues: github.com/NovadaLabs/Novada-proxy/issues
Website: novada.com

License

MIT © Novada — see LICENSE

Novada Proxy（中文文档）

AI 智能体专属住宅代理 MCP — 支持任意供应商。

通过 200 万+ 真实家庭设备（Android 手机、Windows 电脑、Mac）路由 HTTP 请求，绕过反机器人系统，按国家/城市精准定位，跨请求保持同一 IP。

[返回英文] [10 个工具] [5 个提示词] [5 个资源] [430 个测试]

工具 · 提示词 · 资源 · 安装 · 智能体优先 · 供应商

支持 Claude Code、Cursor、Windsurf、Cline、Continue 及所有 MCP 兼容智能体。由 Novada 提供支持。

[!TIP] 免费套餐 — 在 novada.com 注册，无需信用卡。免费使用 Scraper API、Web Unblocker 和住宅代理。

10 个工具

novada_proxy_fetch       → 通过住宅代理抓取任意 URLnovada_proxy_batch_fetch → 并发抓取 2-20 个 URL（最高 5 倍加速）novada_proxy_extract     → 从页面提取结构化字段（标题、价格、评分…）novada_proxy_map         → 爬取页面，返回所有内部链接 JSON 数组novada_proxy_crawl       → 递归爬取站点（BFS，深度 1-5），自动发现 URLnovada_proxy_session     → 粘性会话 — 同一 session_id 始终同一 IPnovada_proxy_search      → Google 搜索，返回结构化 JSON（无需解析 HTML）novada_proxy_render      → 真实 Chromium 渲染 JS 页面 [BETA]novada_proxy_research    → 一键深度研究 — 搜索 + 抓取 + 综合分析novada_proxy_status      → 检查代理网络健康状态

novada_proxy_fetch       → 通过住宅代理抓取任意 URLnovada_proxy_batch_fetch → 并发抓取 2-20 个 URL（最高 5 倍加速）novada_proxy_extract     → 从页面提取结构化字段（标题、价格、评分…）novada_proxy_map         → 爬取页面，返回所有内部链接 JSON 数组novada_proxy_crawl       → 递归爬取站点（BFS，深度 1-5），自动发现 URLnovada_proxy_session     → 粘性会话 — 同一 session_id 始终同一 IPnovada_proxy_search      → Google 搜索，返回结构化 JSON（无需解析 HTML）novada_proxy_render      → 真实 Chromium 渲染 JS 页面 [BETA]novada_proxy_research    → 一键深度研究 — 搜索 + 抓取 + 综合分析novada_proxy_status      → 检查代理网络健康状态

5 个提示词

预构建的智能体工作流，将多个工具链式组合。

提示词	描述	主要参数
`fetch_url`	通过住宅代理抓取 URL，自动绕过反机器人	`url`, `country`, `format`
`research_topic`	搜索 + 批量阅读工作流 — 搜索主题并阅读排名靠前的页面	`query`, `num_results`, `country`
`extract_product`	从任意电商 URL 提取结构化产品数据	`url`, `fields`
`crawl_site`	发现站点所有页面，然后并行抓取	`url`, `limit`, `country`
`troubleshoot`	代理故障逐步诊断	`error_message`

5 个资源

智能体可随时读取的参考数据，无需消耗代理额度。

资源 URI	描述
`proxy://countries`	195+ 国家代码完整列表，含城市级定位
`proxy://error-codes`	所有类型化错误码及恢复指令
`proxy://workflows`	常用智能体工作流模式（爬取、研究、监控）
`proxy://supported-fields`	`novada_proxy_extract` 支持的所有提取字段及策略
`proxy://cost-guide`	每个工具的额度消耗、缓存行为、成本优化技巧

快速决策指南

我想要...	使用工具
抓取单个 URL	`novada_proxy_fetch`
同时抓取 2-20 个 URL	`novada_proxy_batch_fetch`
提取特定字段（标题、价格…）	`novada_proxy_extract` 使用 `fields`
提取任意字段（Schema 模式）	`novada_proxy_extract` 使用 `schema`
获取页面上的所有链接	`novada_proxy_map`
爬取整个站点	`novada_proxy_crawl`
研究某个主题	`novada_proxy_research`
搜索 Google	`novada_proxy_search`
渲染 JS 重型页面	`novada_proxy_render`
跨请求保持同一 IP	`novada_proxy_session`
检查代理是否正常	`novada_proxy_status`

工具选择决策树

目标：抓取单个 URL  ├─ 静态 HTML 页面？                    → novada_proxy_fetch  ├─ 需要特定字段（价格/标题）？          → novada_proxy_extract（fields 或 schema 模式）  └─ React/Vue SPA / 内容为空？          → novada_proxy_render
目标：批量抓取多个 URL  ├─ 已有 URL 列表？                     → novada_proxy_batch_fetch  ├─ 需要获取单页链接？                  → novada_proxy_map → novada_proxy_batch_fetch  └─ 需要爬取整个站点？                  → novada_proxy_crawl → novada_proxy_batch_fetch
目标：研究某个主题                       → novada_proxy_research（一次调用搜索 + 抓取 + 分析）
目标：网页搜索                          → novada_proxy_search → novada_proxy_batch_fetch
目标：登录 + 多步骤流程                  → novada_proxy_session（相同 session_id）
目标：验证代理是否正常工作               → novada_proxy_status

目标：抓取单个 URL  ├─ 静态 HTML 页面？                    → novada_proxy_fetch  ├─ 需要特定字段（价格/标题）？          → novada_proxy_extract（fields 或 schema 模式）  └─ React/Vue SPA / 内容为空？          → novada_proxy_render
目标：批量抓取多个 URL  ├─ 已有 URL 列表？                     → novada_proxy_batch_fetch  ├─ 需要获取单页链接？                  → novada_proxy_map → novada_proxy_batch_fetch  └─ 需要爬取整个站点？                  → novada_proxy_crawl → novada_proxy_batch_fetch
目标：研究某个主题                       → novada_proxy_research（一次调用搜索 + 抓取 + 分析）
目标：网页搜索                          → novada_proxy_search → novada_proxy_batch_fetch
目标：登录 + 多步骤流程                  → novada_proxy_session（相同 session_id）
目标：验证代理是否正常工作               → novada_proxy_status

三大流水线模式

全站爬取流水线（推荐）

novada_proxy_map(url, limit=50)        │        ▼  返回 20-50 个内部链接（1 credit，4 秒）        │        ▼novada_proxy_batch_fetch(urls, concurrency=5)        │        ▼  并发抓取所有页面（N credits，~4 秒，比串行快 15x）

novada_proxy_map(url, limit=50)        │        ▼  返回 20-50 个内部链接（1 credit，4 秒）        │        ▼novada_proxy_batch_fetch(urls, concurrency=5)        │        ▼  并发抓取所有页面（N credits，~4 秒，比串行快 15x）

搜索研究流水线

novada_proxy_search(query, num=10)        │        ▼  结构化 JSON：标题 + URL + 摘要        │        ▼novada_proxy_batch_fetch(urls, format="markdown")        │        ▼  全部页面内容并行返回

novada_proxy_search(query, num=10)        │        ▼  结构化 JSON：标题 + URL + 摘要        │        ▼novada_proxy_batch_fetch(urls, format="markdown")        │        ▼  全部页面内容并行返回

粘性会话 — 登录 + 多页抓取

session_id = "job_001"
novada_proxy_session(session_id, url="/login")    → 同一 IPnovada_proxy_session(session_id, url="/dashboard") → 同一 IPnovada_proxy_session(session_id, url="/data/1")    → 同一 IPnovada_proxy_session(session_id, url="/data/2")    → 同一 IP

session_id = "job_001"
novada_proxy_session(session_id, url="/login")    → 同一 IPnovada_proxy_session(session_id, url="/dashboard") → 同一 IPnovada_proxy_session(session_id, url="/data/1")    → 同一 IPnovada_proxy_session(session_id, url="/data/2")    → 同一 IP

智能体优先设计

[!NOTE] Novada Proxy 是唯一专为自主 AI 智能体设计的代理 MCP。每个响应、错误和描述都为机器消费而优化。

特性	含义
错误中的 `agent_instruction`	每个错误都告诉智能体下一步该做什么
描述中的决策树	每个工具都有 WHEN TO USE / USE INSTEAD 指引
`cache_hit` 元数据	智能体知道是否消耗了 0 额度（缓存命中）
`credits_estimated`	每个响应都内置成本追踪
类型化错误码	机器可读：`BOT_DETECTION_SUSPECTED`、`PAGE_NOT_FOUND` 等
5 个工作流提示词	预构建工作流：研究、爬取、提取、诊断
5 个参考资源	国家、错误码、成本指南 — 随时可访问

核心特性

1. 住宅 IP 网络

200 万+ 真实设备：Android 手机、Windows 电脑、Mac
7,000+ 活跃节点，99.9% 在线率
真实家庭 IP 指纹，绕过 Cloudflare、Akamai、DataDome 检测

2. 地理定向

195+ 国家，两字母 ISO 代码（US、DE、JP、BR...）
城市级定位：newyork、london、tokyo、singapore...
同一 URL 不同国家 = 独立缓存键，互不干扰

3. 响应缓存

重复抓取相同 URL 不消耗代理额度：

json

// 第一次调用（live fetch）"meta": { "cache_hit": false, "latency_ms": 1800, "quota": { "credits_estimated": 1 } }
// 第二次调用（cache hit）"meta": { "cache_hit": true, "cache_age_seconds": 5, "latency_ms": 0 }

// 第一次调用（live fetch）"meta": { "cache_hit": false, "latency_ms": 1800, "quota": { "credits_estimated": 1 } }
// 第二次调用（cache hit）"meta": { "cache_hit": true, "cache_age_seconds": 5, "latency_ms": 0 }

配置项	说明
默认 TTL	300 秒（5 分钟）
缓存键	`url + format + country`
禁用缓存	`PROXY4AGENT_CACHE_TTL_SECONDS=0`
session_id	有 session_id 的请求永不缓存（粘性路由需要实时调用）

4. 智能体优先的 JSON 输出

所有工具返回统一结构：

json

{  "ok": true / false,  "tool": "工具名称",  "data": { ... },  "meta": {    "latency_ms": 1800,    "cache_hit": false,    "quota": { "credits_estimated": 1 }  }}

{  "ok": true / false,  "tool": "工具名称",  "data": { ... },  "meta": {    "latency_ms": 1800,    "cache_hit": false,    "quota": { "credits_estimated": 1 }  }}

5. 类型化错误码 + 恢复指令

每个错误都包含 code（枚举）、recoverable（布尔）、agent_instruction（下一步操作）：

json

{  "ok": false,  "error": {    "code": "BOT_DETECTION_SUSPECTED",    "recoverable": true,    "agent_instruction": "Try novada_proxy_render (real browser). Or retry with a different country/session_id."  }}

{  "ok": false,  "error": {    "code": "BOT_DETECTION_SUSPECTED",    "recoverable": true,    "agent_instruction": "Try novada_proxy_render (real browser). Or retry with a different country/session_id."  }}

错误码	含义	可恢复
`BOT_DETECTION_SUSPECTED`	被目标站点封锁（403）	✓
`TLS_ERROR`	TLS/SSL 连接失败	✓
`TIMEOUT`	请求超时	✓
`RATE_LIMITED`	HTTP 429 限速	✓
`NETWORK_ERROR`	DNS 解析失败	✗
`INVALID_INPUT`	参数错误	✗
`PROVIDER_NOT_CONFIGURED`	缺少凭证	✗

6. 批量并发抓取

novada_proxy_batch_fetch 内置信号量并发控制：

json

// 10 个 URL，concurrency=5，wall time = ~8.8s（串行估计 ~50s）{  "data": {    "results": [      { "url": "...", "ok": true, "cache_hit": false, "latency_ms": 1200 },      { "url": "...", "ok": true, "cache_hit": true,  "latency_ms": 0 },      { "url": "...", "ok": false, "error": { "code": "TLS_ERROR" } }    ]  },  "meta": { "latency_ms": 8800, "quota": { "credits_estimated": 10 } }}

// 10 个 URL，concurrency=5，wall time = ~8.8s（串行估计 ~50s）{  "data": {    "results": [      { "url": "...", "ok": true, "cache_hit": false, "latency_ms": 1200 },      { "url": "...", "ok": true, "cache_hit": true,  "latency_ms": 0 },      { "url": "...", "ok": false, "error": { "code": "TLS_ERROR" } }    ]  },  "meta": { "latency_ms": 8800, "quota": { "credits_estimated": 10 } }}

7. 多供应商支持

供应商	环境变量	说明
Novada（推荐）	`NOVADA_PROXY_USER` + `NOVADA_PROXY_PASS`	最深度集成，含搜索 + 浏览器 API
BrightData	`BRIGHTDATA_USER` + `BRIGHTDATA_PASS`	完整自动定位
Smartproxy	`SMARTPROXY_USER` + `SMARTPROXY_PASS`	完整自动定位
Oxylabs	`OXYLABS_USER` + `OXYLABS_PASS`	完整自动定位
通用 HTTP	`PROXY_URL=http://user:pass@host:port`	任意代理服务商

8. 渐进式降级（render_fallback）

novada_proxy_extract 支持自动升级到浏览器渲染：

代理抓取失败（TLS / Bot检测）        │        ▼ render_fallback=truenovada_proxy_render（真实 Chromium）        │        ▼data.extracted_via = "render"  （agent 知道走了哪条路径）data.fetch_warning = "Proxy fetch failed... escalated to render"

代理抓取失败（TLS / Bot检测）        │        ▼ render_fallback=truenovada_proxy_render（真实 Chromium）        │        ▼data.extracted_via = "render"  （agent 知道走了哪条路径）data.fetch_warning = "Proxy fetch failed... escalated to render"

快速安装

bash

# 核心（住宅代理抓取）claude mcp add novada-proxy-mcp \  -e NOVADA_PROXY_USER=你的用户名 \  -e NOVADA_PROXY_PASS=你的密码 \  -- npx -y novada-proxy-mcp
# 仅搜索claude mcp add novada-proxy-mcp \  -e NOVADA_API_KEY=你的_API_Key \  -- npx -y novada-proxy-mcp
# 全功能（代理 + 搜索 + 浏览器渲染）claude mcp add novada-proxy-mcp \  -e NOVADA_PROXY_USER=你的用户名 \  -e NOVADA_PROXY_PASS=你的密码 \  -e NOVADA_API_KEY=你的_API_Key \  -e NOVADA_BROWSER_WS=你的_Browser_WS_URL \  -- npx -y novada-proxy-mcp

# 核心（住宅代理抓取）claude mcp add novada-proxy-mcp \  -e NOVADA_PROXY_USER=你的用户名 \  -e NOVADA_PROXY_PASS=你的密码 \  -- npx -y novada-proxy-mcp
# 仅搜索claude mcp add novada-proxy-mcp \  -e NOVADA_API_KEY=你的_API_Key \  -- npx -y novada-proxy-mcp
# 全功能（代理 + 搜索 + 浏览器渲染）claude mcp add novada-proxy-mcp \  -e NOVADA_PROXY_USER=你的用户名 \  -e NOVADA_PROXY_PASS=你的密码 \  -e NOVADA_API_KEY=你的_API_Key \  -e NOVADA_BROWSER_WS=你的_Browser_WS_URL \  -- npx -y novada-proxy-mcp

获取凭证：novada.com -> 仪表盘 -> 住宅代理 -> 端点生成器

Cursor / Windsurf / Cline 配置：

json

{  "mcpServers": {    "novada-proxy-mcp": {      "command": "npx",      "args": ["-y", "novada-proxy-mcp"],      "env": {        "NOVADA_PROXY_USER": "你的用户名",        "NOVADA_PROXY_PASS": "你的密码"      }    }  }}

{  "mcpServers": {    "novada-proxy-mcp": {      "command": "npx",      "args": ["-y", "novada-proxy-mcp"],      "env": {        "NOVADA_PROXY_USER": "你的用户名",        "NOVADA_PROXY_PASS": "你的密码"      }    }  }}

工具参数速查

novada_proxy_fetch

参数	类型	默认	说明
`url`	string	必填	目标 URL
`country`	string	—	国家代码（`US`、`DE`、`JP`...）
`city`	string	—	城市（`newyork`、`london`...）
`session_id`	string	—	复用同一 IP（不含连字符，最多 64 字符）
`format`	string	`markdown`	`markdown`（去 HTML）或 `raw`（原始 HTML）
`timeout`	number	`60`	超时秒数（1-120）

novada_proxy_batch_fetch

novada_proxy_extract

参数	类型	默认	说明
`url`	string	必填	目标 URL
`fields`	string[]	必填	要提取的字段（`title`、`price`、`description`、`rating`...）
`render_fallback`	boolean	`false`	代理失败时自动切换到浏览器渲染
`country`	string	—	地理定向

novada_proxy_map

novada_proxy_session

参数	类型	默认	说明
`session_id`	string	必填	会话 ID（不含连字符，最多 64 字符）
`url`	string	必填	目标 URL
`verify_sticky`	boolean	`false`	验证 IP 一致性（需额外 15-25 秒）
`country`	string	—	国家代码

novada_proxy_search

novada_proxy_render [BETA]

参数	类型	默认	说明
`url`	string	必填	目标 URL
`format`	string	`markdown`	`markdown` · `html` · `text`
`wait_for`	string	—	等待 CSS 选择器后再提取（如 `.product-title`）
`timeout`	number	`60`	超时秒数（5-120）

novada_proxy_crawl

递归 BFS 爬取站点，从起始 URL 出发，按深度逐层发现链接，返回完整 URL 树及元数据。

参数	类型	默认	说明
`url`	string	必填	起始 URL
`depth`	number	`2`	BFS 深度（1-5）
`limit`	number	`50`	最大爬取页数（10-200）
`include_content`	boolean	`false`	同时返回每个页面的内容
`country`	string	—	地理定向所有请求
`format`	string	`markdown`	`include_content: true` 时的内容格式
`timeout`	number	`60`	每页超时秒数

适用场景：全站抓取、站点地图生成、内容索引 — 需要抓取多个页面时使用。

改用 novada_proxy_map 的情况：只需要单页链接（一层深度）。Map 更快、更省额度。

组合使用：将 data.urls[] 传入 novada_proxy_batch_fetch 并发抓取。

请求示例：

响应： data.pages[]（url、depth、status_code、total_links），data.urls[]（扁平数组，可直接传给 novada_proxy_batch_fetch）

novada_proxy_research

一键深度研究工具 — 搜索网络、抓取排名靠前的结果，返回含来源预览的结构化分析。智能体可对 findings 进行进一步综合分析。

参数	类型	默认	说明
`query`	string	必填	研究问题或主题
`depth`	string	`"standard"`	`"quick"`（3 个来源）、`"standard"`（5 个）、`"deep"`（10 个）
`country`	string	—	本地化搜索结果
`timeout`	number	`60`	超时秒数

需要： NOVADA_API_KEY（Google 搜索）+ 代理凭证（抓取来源页面）

适用场景：研究问题、主题调研、竞品分析、事实核查 — 需要一次调用获取多个来源内容时。

改用 novada_proxy_search 的情况：只需要搜索结果 URL，不需要完整页面内容。

组合使用：对 data.urls[] 中的特定 URL 调用 novada_proxy_fetch 进行深度阅读。

注意： findings_summary 是各来源内容的拼接预览 — 智能体应分析 findings[] 进行实质性综合。

请求示例：

响应： data.findings[]（title、url、snippet、content_preview），data.urls[]（可链式传给其他工具），data.findings_summary

novada_proxy_extract — Schema 模式（LLM 提取）

除 fields（启发式提取）外，novada_proxy_extract 还支持 schema 参数，通过智能体自身的 LLM 提取任意字段 — 零额外 API 费用。

传入 schema 替代 fields，工具返回清洗后的页面内容 + 提取提示词 — 由你的智能体完成提取。

参数	类型	默认	说明
`url`	string	必填	目标 URL
`schema`	object	—	键 = 字段名，值 = 字段描述。替代 `fields` 使用。
`render_fallback`	boolean	`false`	代理失败时自动切换到浏览器渲染
`country`	string	—	地理定向
`timeout`	number	`60`	超时秒数

请求示例：

json

{  "url": "https://example.com/product",  "schema": {    "product_name": "完整的产品名称",    "price": "当前价格（含货币符号）",    "warranty": "保修条款和期限",    "return_policy": "退货政策摘要"  }}

{  "url": "https://example.com/product",  "schema": {    "product_name": "完整的产品名称",    "price": "当前价格（含货币符号）",    "warranty": "保修条款和期限",    "return_policy": "退货政策摘要"  }}

响应： data.mode = "llm_extract"，data.content（清洗后的 Markdown 内容），data.extraction_prompt（供智能体遵循并提取字段的指令）

安全限制： Schema 键名只能包含字母、数字、下划线（a-z、0-9、_），最多 50 字符；值最多 200 字符。

使用场景

AI 智能体需要：

抓取电商网站（Amazon、eBay、Walmart）不被封锁
跨国家监控价格变动
访问 195+ 国家的地区限制内容
对 Cloudflare/Akamai 保护站点进行竞争情报收集
执行多步登录流程并保持同一 IP
渲染无真实浏览器就返回空白的 JS 页面
Google 搜索返回结构化 JSON 结果

开发者构建：

AI 驱动的网页研究工具
价格比较智能体
全站内容爬取管道
SEO 监控仪表盘
市场调研自动化

已验证可用

电商： Amazon、eBay、Walmart、Etsy、Shopify
职业网络： LinkedIn
反机器人保护： Cloudflare 站点、Akamai、DataDome
新闻内容： HackerNews、Reddit、BBC、CNN、NYTimes
科技： GitHub、Wikipedia、Stack Overflow、IMDB

反馈与支持

邮箱： [email protected]
GitHub Issues： github.com/NovadaLabs/Novada-proxy/issues
官网： novada.com

许可证

MIT © Novada

來源：README.md，提交 f359840

工具

SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

v1.7.0最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。
已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。
已列出工具15 分
請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。
描述必需15 分
圖示10 分
文件15 分
授權條款10 分

Metric	Value
Residential IPs	2,000,000+
Live nodes	7,000+
Countries	195+
Device types	Android, Windows, Mac
Uptime	99.9%

Parameter	Type	Default	Description
`query`	string	required	Search query
`num`	number	`10`	Results (1–20)
`country`	string	—	Localize: `us`, `uk`, `de`, `jp`...
`language`	string	—	Language: `en`, `zh`, `de`, `ja`...

Proxy4agents Mcp

概覽

安裝

在 SourceWeft 中

其他 MCP 客戶端

README

Novada Proxy

Getting Started

For Humans

For Agents

Why Novada Proxy

10 Tools at a Glance

Quick Decision Guide

When To Use Which Tool

5 Prompts

5 Resources

Quick Install

Providers

Agent-First Design

Tools

novada_proxy_fetch

novada_proxy_batch_fetch

novada_proxy_extract

novada_proxy_map

novada_proxy_session

novada_proxy_search

novada_proxy_render [BETA]

novada_proxy_crawl

novada_proxy_research

novada_proxy_extract — Schema Mode

Schema Mode (LLM Extraction)

novada_proxy_status

Agent Workflows

Site crawl pipeline (map -> batch)

Research pipeline (search -> batch)

Sticky session — login + multi-page scrape

Price monitoring — same product, three markets

Extract structured data

Response Cache

Typed Error Codes

Geo Coverage

Compatible With

Network

Confirmed Working

Real-World Test Results

Proxy Type Guide

Known Limitations

Feedback & Support

License

Novada Proxy（中文文档）

10 个工具

5 个提示词

5 个资源

快速决策指南

工具选择决策树

三大流水线模式

全站爬取流水线（推荐）

搜索研究流水线

粘性会话 — 登录 + 多页抓取

智能体优先设计

核心特性

1. 住宅 IP 网络

2. 地理定向

3. 响应缓存

4. 智能体优先的 JSON 输出

5. 类型化错误码 + 恢复指令

6. 批量并发抓取

7. 多供应商支持

8. 渐进式降级（render_fallback）

快速安装

工具参数速查

novada_proxy_fetch

novada_proxy_batch_fetch

novada_proxy_extract

novada_proxy_map

novada_proxy_session

novada_proxy_search

novada_proxy_render [BETA]

novada_proxy_crawl

novada_proxy_research

`novada_proxy_fetch`

`novada_proxy_batch_fetch`

`novada_proxy_extract`

`novada_proxy_map`

`novada_proxy_session`

`novada_proxy_search`

`novada_proxy_render` [BETA]

`novada_proxy_crawl`

`novada_proxy_research`

`novada_proxy_extract` — Schema Mode

`novada_proxy_status`