# novada-mcp [Health: Active]

**Category:** 🔎 Search & Data Extraction  
**Repository:** https://github.com/NovadaLabs/novada-mcp  
**GitHub Stars:** 3  
**npm Downloads (last month):** 2310  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/novada-mcp

## Description
Search, extract, crawl, map, research, scrape 16 platforms, browser automation, proxy — one API key.

## Tools
Capabilities this server exposes over MCP:

- **novada_search** — Search the web for clean, ready-to-use content — titles, URLs, snippets, reranked by relevance. For multi-source questions, use novada_research instead (faster, more thorough).

**Use for:** current events, URL lookup, fact-checking, competitive research. enrich_top=true auto-extracts the #1 result.
**Not for:** a known URL (novada_extract) or a multi-source report (novada_research).
**Tip:** engine='google' (default) is fastest/most reliable; duckduckgo/yandex are slower fallbacks.
**Domain filtering:** includeDomains/excludeDomains inject `site:domain` into the query (not API-side).
**Project grouping:** `project="my-project"` groups outputs under a subfolder (~/Downloads/novada-mcp/<date>/<project>/).
- **novada_extract** — Extract content from any URL. Auto-handles Cloudflare/DataDome/Kasada via escalation (static → JS render → Browser CDP). Batch mode: pass url as an array for up to 10 pages in parallel.

**Format selection:**
- `format="markdown"` (default): full-page content for reading/analysis.
- `format="json"`: structured object (url, title, content, quality, links, structured_data, fields, hints, mode, fetched_at). Use with `fields=["price","title"]` to populate `fields`. Common mistake: using markdown when you need specific fields — use format="json"+fields instead.
- `format="html"`: raw HTML (truncated at 100K chars by default; adjust via max_chars).
- `clean=true`: strip nav/sidebar, main content only (~15K chars vs ~100K full page).

**Use for:** reading pages, batch-extracting search results, structured fields (price, author, date) — works on anti-bot pages automatically.
**Not for:** URL discovery (novada_map), multi-page crawl (novada_crawl), rich platform data like Amazon/LinkedIn (novada_scrape).
**Key rule:** leave render="auto" (default) — 15-100x faster on static sites; only set render="render" for known JS-heavy SPAs.
**Geo-routing:** `country="de"` (ISO 2-letter) routes render fetches through that country's exit IP — for localized pricing or geo-restricted content.
**Auto-saved:** every extraction is written to `~/Downloads/novada-mcp/YYYY-MM-DD/` (path shown in the response).
**Project grouping:** `project="my-project"` groups outputs under a subfolder.
- **novada_crawl** — Use when you need content from a bounded set of pages (up to 20) and don't have the URLs yet. Crawls BFS/DFS, extracts each page inline. Use select_paths globs to target sections (e.g. "/docs/api/**").

**Wrong tool for whole-site jobs:** for >20 pages or a full docs site on disk, use `novada_site_copy` instead (up to 1000 pages, streams to disk, returns a manifest). novada_crawl hard-caps at 20 pages and returns bodies inline.

**Best for:** competitive content analysis, a handful of related pages inline (returns bodies directly).
**Not for:** a single page (novada_extract), URL discovery only (novada_map — much faster), a whole site to disk (novada_site_copy).
**Performance:** avoid max_pages > 10 on large sites — crawl time scales ~1.4s/page (max_pages=20 ≈ 28s minimum). Use select_paths to narrow scope before raising max_pages.
**Rendering:** `render` defaults to "auto" (static first, escalates to JS on detection) — not static-only.
- **novada_research** — One call → 3-10 parallel searches across Google/Bing/DuckDuckGo → dedup → extracts full content from top sources → returns CITED SOURCE MATERIAL (numbered passages), not a written answer. Extractive, not generative — you compose the final answer from the gathered passages.

**Use for:** complex questions needing passages from ≥3 independent sources in one call — comparative analysis, market research, technical deep dives, competitive intelligence. Replaces 5-10 manual search+extract calls.
**Not for:** a single fact or one URL (novada_search — faster/cheaper), a known URL (novada_extract), or a finished prose report (this returns source material, not an answer).
**Depth:** "quick" (3 queries), "deep" (6), "comprehensive" (8-9), "auto" (default — quick or deep by question length, never comprehensive).
**Project grouping:** `project="my-project"` groups outputs under a subfolder.
**Recency:** `time_range` ("day"|"week"|"month"|"year"), `start_date`/`end_date` (ISO YYYY-MM-DD) propagate to every internal search call.
**Response size:** extracts full content from the top 5 sources only (even at depth="comprehensive"); each source is capped at novada_extract's own default 25,000-char limit — bounded total, not unbounded "every source in full."
- **novada_map** — Discover URLs on a site before deciding what to read. Tries sitemap.xml first (fast), falls back to BFS crawl. Returns URLs only — no content. Hard cap: 100 URLs.

**Best for:** site structure discovery, finding the right subpage, pre-flight before novada_crawl/novada_extract.
**Not for:** reading content (use novada_crawl/novada_extract) or copying a whole site to disk (novada_site_copy).
**Note:** limited results on JS SPAs — flagged in the output.
- **novada_site_copy** — Copy an entire docs site/section to disk as clean markdown — one.md file per page — returning a COMPACT manifest, not page bodies. Use for a whole knowledge base on disk (offline docs ingest, RAG corpus, full-site mirror).

**Discovery order:** (1) llms.txt/llms-full.txt if present, (2) sitemap.xml, (3) scoped same-host BFS to completion. select_paths/exclude_paths and same-host are always enforced.
**Best for:** "copy all of docs.x.com", a local docs corpus, ingesting an llms.txt index.
**Not for:** a single page (novada_extract), a few pages inline (novada_crawl), URL discovery only (novada_map).
**Output:** each page streams to `~/Downloads/novada-mcp/<date>/<project|domain>/site-copy/<slug>.md`; `manifest.json` records {url,file,title,word_count,depth,bytes,status} per page. The tool returns a compact summary + manifest path, not inline content — read the.md files or manifest.json after it completes.
**Scale:** max_pages default 200, hard max 1000, drained until the queue is empty or the ceiling is hit.
- **novada_scrape** — Use for structured data from a specific platform — clean tabular records, not raw HTML. Proxies the Novada Scraper API (scraper.novada.com; public docs: https://developer.novada.com/novada/advanced-proxy-solutions/scraper-api/target-sites-supported-by-scraper-api). Supports 14 platforms (~76 operations): Google, LinkedIn, Amazon, YouTube, Walmart, DuckDuckGo, TikTok, Bing, Instagram, X (Twitter), Facebook, Perplexity AI, Yandex, GitHub.

**Best for:** e-commerce product data, social posts/comments, job listings, reviews, real estate, market data.
**Not for:** general web pages outside this platform list — use novada_extract instead.
**Prefer the dedicated tool when one exists:** for amazon/google/bing/duckduckgo/yandex/youtube/instagram/facebook/tiktok/x/walmart/linkedin/github/perplexity, call novada_scrape_<platform> instead — same engine, but its `operation` enum uses typed friendly names and is rejected client-side before any network call if wrong. Use THIS generic tool for platforms with no dedicated sibling or when resuming by task_id.
**Output formats:** markdown (default table), json (records array inside a fenced "## Scrape Results" block), toon (pipe-separated, 40-65% smaller — best for large result sets), csv, excel (base64), html.
**Example:** platform="amazon.com", operation="amazon_product_keywords", params={keyword:"iphone 16", num:5}.
**Amazon price fields:** trust `final_price`/`price` (check `_price_source`) — `initial_price` and `buybox_prices.final_price` are often 0 by design, not a bug; `buybox_prices.unit_price` is raw per-unit data, never the listing price.
**Discover platforms:** read the `novada://scraper-platforms` resource for the full, always-current operation list (slugs + required params), or see the public reference at https://developer.novada.com/novada/advanced-proxy-solutions/scraper-api/target-sites-supported-by-scraper-api.
**Resume:** pass `task_id` from a prior status:processing call to fetch the result without a new billable task (platform/operation still required, display-only).
**Project grouping:** `project="my-project"` groups outputs under a subfolder.
- **novada_scrape_amazon** — Extract structured Amazon data — product details, reviews, seller info, bestseller lists, category/brand listings — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="amazon.com").

**Use when:** "get the price/rating/title for Amazon ASIN B0...", "pull the reviews for this Amazon product URL", "search Amazon for <keyword> with price and rating", "who is this Amazon seller", "what's in this Amazon Best Sellers list".
**Not for:** Any other platform — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). A general Google/web search — use novada_search. Reading one arbitrary URL's raw content — use novada_extract.
**Returns:** Structured product/review/seller records (title, price, rating, asin, availability, etc.) in the chosen output format — same rendering as novada_scrape.
**Ops:** 10 verified-working Amazon operations. 3 known backend-broken ones are excluded from this enum (rejected client-side before any backend call) — unlike novada_scrape(platform="amazon.com",...), which still forwards them with a warning.
- **novada_scrape_google** — Extract structured Google SERP data — organic web search, AI Mode answers, Maps place/review details, Shopping, Jobs, Hotels, Videos — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="google.com"). Returns raw structured SERP records, not a generated answer.

**Use when:** "get the raw Google search results (titles, links, ranks) for <query>", "what's in Google's AI Mode answer for <query>", "pull Google Maps reviews or place details for this URL / place_id / CID", "search Google Shopping for <keyword>", "find Google Jobs, Hotels, or Videos results for <query>".
**Not for:** A general question needing just an answer or a few good links — use novada_search (multi-engine: google/duckduckgo/yandex, ranked/reranked, cheaper than a raw-SERP scrape). A complex question needing cited multi-source synthesis — use novada_research. Reading one already-known URL's page content — use novada_extract. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>").
**Returns:** Structured SERP records per operation — organic results (title/url/snippet/rank), AI Mode answer content, Maps place details/reviews, Shopping listings (price/rating), Jobs/Hotels/Videos listings — in the chosen output format, same rendering as novada_scrape.
**Ops:** 13 verified-working Google operations spanning web search, AI Mode, Maps (location/place_id/CID/URL lookups + reviews), Shopping, Jobs, Hotels, and Videos. Every google.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.
- **novada_scrape_bing** — Extract structured Bing SERP data — organic web search, video results, news results, shopping listings — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="bing.com"). Bing is NOT a selectable engine on novada_search — this is the only intentional way to query Bing specifically.

**Use when:** "get the raw Bing search results (titles, links, ranks) for <query>", "find Bing video results for <query>", "find Bing news results for <query>, sorted by date", "search Bing Shopping for <keyword>".
**Not for:** A general question needing just an answer or a few good links — use novada_search — google/duckduckgo/yandex only (Bing is not selectable there); ranked, cheaper than a raw-SERP scrape. A complex question needing cited multi-source synthesis — use novada_research. Reading one already-known URL's page content — use novada_extract. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>").
**Returns:** Structured SERP records per operation — organic results (title/url/snippet/rank), video results, news results (with date), shopping listings (price/rating) — in the chosen output format, same rendering as novada_scrape.
**Ops:** 4 verified-working Bing operations: web search, videos, news, and shopping. Every bing.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.
- **novada_scrape_duckduckgo** — Extract structured DuckDuckGo web search SERP data via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="duckduckgo.com"). Returns the raw organic-results SERP, with region/time/adult-content filters novada_search does not expose, not a generated answer.

**Use when:** "get the raw DuckDuckGo search results (titles, links, ranks) for <query>", "search DuckDuckGo restricted to a specific region (params.kl) or time range (params.df)", "compare DuckDuckGo's ranking for <query> against another engine's raw SERP".
**Not for:** A general question needing just an answer or a few good links — use novada_search with engine="duckduckgo" (ranked/reranked instead of a raw SERP dump). A complex question needing cited multi-source synthesis — use novada_research. Reading one already-known URL's page content — use novada_extract. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>").
**Returns:** Structured organic-result SERP records (title/url/snippet/rank) in the chosen output format, same rendering as novada_scrape.
**Ops:** 1 verified-working DuckDuckGo operation (web search). The single duckduckgo.com catalog operation is currently status:"ok".
- **novada_scrape_yandex** — Extract structured Yandex web search SERP data via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="yandex.com"). Returns the raw organic-results SERP, with TLD/language/time-range controls novada_search does not expose, not a generated answer.

**Use when:** "get the raw Yandex search results (titles, links, ranks) for <query>", "search a specific Yandex TLD (params.yandex_domain, e.g. "yandex.ru") for Russian/Eastern European content", "search Yandex restricted to a time range (params.within)".
**Not for:** A general question needing just an answer or a few good links — use novada_search with engine="yandex" (ranked/reranked instead of a raw SERP dump). A complex question needing cited multi-source synthesis — use novada_research. Reading one already-known URL's page content — use novada_extract. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>").
**Returns:** Structured organic-result SERP records (title/url/snippet/rank) in the chosen output format, same rendering as novada_scrape.
**Ops:** 1 verified-working Yandex operation (web search, requires params.yandex_domain TLD selector). The single yandex.com catalog operation is currently status:"ok".
- **novada_scrape_youtube** — Extract structured YouTube data — video/channel metadata, comments, downloadable video/audio files — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="youtube.com").

**Use when:** "pull the comments on this YouTube video", "get channel info for this YouTube channel URL", "search YouTube channels for <keyword>", "find YouTube videos matching <keyword>, filtered by duration/upload date/attributes", "download a YouTube video or its audio track".
**Not for:** A single YouTube URL to read as plain text — use novada_extract. A general web/video search not scoped to YouTube — use novada_search. The transcript/subtitles of a YouTube video — this operation (transcript_by_video) is currently backend_broken (live-verified 2026-10-13) and has been removed from this tool's enum; no working alternative exists today. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>").
**Returns:** Structured video/channel/comment records (title, views, comment author/text, channel subscriber count, etc.) plus downloadable video/audio file links, in the chosen output format — same rendering as novada_scrape.
**Ops:** 12 verified-working YouTube operations spanning video/audio downloads, channel lookup + search, comments, and video search by keyword/label/filters/playlist/channel. 1 known backend_broken op (transcript_by_video, live-verified 2026-10-13: API_DOWN 404 "subtitles_error: Unable to download API page" across 2 different video_ids) is excluded from this enum.
- **novada_scrape_instagram** — Extract structured Instagram data — profiles, posts, reels, and comments — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="instagram.com").

**Use when:** "get the latest posts from this Instagram profile", "pull the comments on this Instagram post or reel", "get details for this single Instagram post or reel URL", "get Instagram profile info by URL or username", "get the reels posted by this Instagram profile".
**Not for:** A single Instagram URL to read as plain text — use novada_extract. A general web search not scoped to Instagram — use novada_search. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>").
**Returns:** Structured profile/post/reel/comment records (username, follower count, caption, like count, comment author/text, etc.) in the chosen output format — same rendering as novada_scrape.
**Ops:** 7 verified-working Instagram operations spanning profile lookup (by URL or username), posts and reels (by profile or by direct URL), and comments. `posts_by_profile` requires BOTH `profileurl` AND `resultsLimit` together. Every instagram.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.
- **novada_scrape_facebook** — Extract structured Facebook data — public profile pages, posts, comments, and events — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="facebook.com").

**Use when:** "get this public Facebook page's profile info", "pull the comments on this Facebook post", "get details for this Facebook event", "find events matching <query> on Facebook", "list the upcoming events on this Facebook page".
**Not for:** A single Facebook URL to read as plain text — use novada_extract. A general web search not scoped to Facebook — use novada_search. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>").
**Returns:** Structured profile/post/comment/event records (page name, post text, comment author/text, event name/date/location, etc.) in the chosen output format — same rendering as novada_scrape.
**Ops:** 6 verified-working Facebook operations spanning public profile pages, posts, comments, and events (search / single event / event list). Every facebook.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.
- **novada_scrape_tiktok** — Extract structured TikTok data — profile info, post/video details, and post lists by profile, hashtag, or search URL — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="tiktok.com").

**Use when:** "get the latest posts from this TikTok profile", "get details for this single TikTok video URL", "pull TikTok profile info for this URL", "search TikTok profiles from this discover/search URL", "get posts from this TikTok hashtag/discover page".
**Not for:** A single TikTok URL to read as plain text — use novada_extract. A general web search not scoped to TikTok — use novada_search. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>").
**Returns:** Structured profile/post records (username, follower count, video description, likes, view count, etc.) in the chosen output format — same rendering as novada_scrape.
**Ops:** 5 verified-working TikTok operations: profile search by list URL, profile by URL, posts by list URL, posts by profile URL, and a single post by URL. Every tiktok.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.
- **novada_scrape_x** — Extract structured X (Twitter) data — a single post and profile lookups by username or URL — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="x.com").

**Use when:** "get the text/engagement stats for this X post URL", "get this X profile's info by username", "get this X profile's info by profile URL".
**Not for:** A single X/Twitter URL to read as plain text — use novada_extract. A general web search not scoped to X — use novada_search. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>").
**Returns:** Structured post/profile records (post text, like/reply/repost counts, profile bio, follower count, etc.) in the chosen output format — same rendering as novada_scrape.
**Ops:** 3 verified-working X (Twitter) operations: a single post by URL, and profile lookup by username or by profile URL. Every x.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.
- **novada_scrape_walmart** — Extract structured Walmart data — product details by keyword search, category URL, SKU, zip-code-specific pricing, or direct product URL — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="walmart.com").

**Use when:** "search Walmart for <keyword> and give me prices/ratings", "get product listings from this Walmart category URL", "what's the price/availability for this Walmart SKU", "get this Walmart product's info for a specific zip code", "get product details for this Walmart product URL".
**Not for:** A single Walmart URL to read as plain text — use novada_extract. A general web search not scoped to Walmart — use novada_search. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>").
**Returns:** Structured product records (title, price, rating, availability, SKU, etc.) in the chosen output format — same rendering as novada_scrape.
**Ops:** 5 verified-working Walmart operations spanning keyword search, category-URL listings, SKU lookup, zip-code-specific pricing, and direct product URL. `product_by_keyword` requires BOTH `domain` AND `keyword` together; `product_by_category_url` requires ALL THREE of `category_url`, `all`, AND `page_limit` together; `product_by_url_and_zipcode` requires BOTH `url` AND `zipcode` together. Every walmart.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.
- **novada_scrape_linkedin** — Extract structured LinkedIn data — job listings (by location/filters, jobs search-results URL, or a single job posting URL) and company profile info by URL — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="linkedin.com").

**Use when:** "find LinkedIn job listings in <location> matching <keyword/level/remote/etc.>", "get all the job listings from this LinkedIn jobs search URL", "get details for this single LinkedIn job posting URL", "get company info for this LinkedIn company URL".
**Not for:** A single LinkedIn URL to read as plain text — use novada_extract. A general web search not scoped to LinkedIn — use novada_search. A LinkedIn personal PROFILE (not a company or job) — no catalog operation exists for this today — use novada_extract on the profile URL, or novada_search. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>").
**Returns:** Structured job-listing/company records (title, location, level, company name, follower count, etc.) in the chosen output format — same rendering as novada_scrape.
**Ops:** 4 verified-working LinkedIn operations spanning job search (by location, with optional keyword/level/remote/company filters), job listings from a search-results URL, a single job posting by URL, and company info by URL. `jobs_search` requires `params.location` — the catalog's actual required key for this op, despite its upstream name reading "By Keywords" (keyword itself is optional there). Every linkedin.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.
- **novada_scrape_github** — Extract structured GitHub repository data — repository details by URL, or multiple repositories from a GitHub search-results URL — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="github.com").

**Use when:** "get repository info (stars, forks, description, language, etc.) for this GitHub repo URL", "get the repositories listed on this GitHub search-results URL".
**Not for:** A single GitHub URL (repo, issue, PR, user) to read as plain text — use novada_extract. A general web/code search not scoped to GitHub, or a GitHub issue/PR/user lookup (no catalog operation exists for those) — use novada_search, or novada_extract for a known URL. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>").
**Returns:** Structured repository records (name, description, stars, forks, language, etc.) in the chosen output format — same rendering as novada_scrape.
**Ops:** 3 verified-working GitHub operations: two repository-by-URL lookups (`repository_by_url` and `repository_details_by_url` map to distinct catalog scraper_ids — github_repository_repo-url and github_repository_url respectively — both taking the same `url` param; the catalog documents no behavioral difference between them) and repository listing from a GitHub search-results URL. Every github.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.
- **novada_scrape_perplexity** — Extract the actual AI-generated answer Perplexity returns for a query — by a Perplexity query URL or a raw search term — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="perplexity.ai"). Scrapes Perplexity's own live-rendered answer page (the model's actual response text) — NOT a web search results list and NOT an indexed-page brand-mention scan.

**Use when:** "what does Perplexity AI answer for <query>", "get Perplexity's generated answer for this perplexity.ai URL", "get Perplexity's answer for the search term <term>".
**Not for:** A general web/multi-engine search for information (not Perplexity's own generated answer) — use novada_search. Checking whether a brand is mentioned on AI-company indexed public pages — use novada_ai_monitor — scans INDEXED PUBLIC PAGES for brand mentions across AI-company domains; does not fetch a live generated answer for an arbitrary query. A complex question needing cited, multi-source synthesis — use novada_research. Reading one already-known URL's raw page content — use novada_extract. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>").
**Returns:** Perplexity's rendered answer content (the text of its generated response) in the chosen output format — same rendering as novada_scrape.
**Ops:** 2 verified-working Perplexity operations: answer by a perplexity.ai query URL, or answer by a raw search term. Every perplexity.ai catalog operation is currently status:"ok" — unlike its sibling chatgpt.com, whose only 2 catalog operations are BOTH backend_broken (verified 2026-07-13, "submit hangs >120s"), which is why no dedicated chatgpt.com scraper tool exists.
- **novada_proxy** — Route your own HTTP requests through residential or mobile IPs — geo-targeting, IP rotation, bypassing IP-based rate limits. Returns a proxy URL, shell exports, or a curl --proxy flag (format=url|env|curl).

**Best for:** a specific country/city IP, sticky multi-step sessions, testing geo-restricted content.
**Not for:** page extraction (novada_extract — proxy is automatic) or web search (novada_search).
**Returns a masked config:** username shown as `<PROXY_USER>`, password as `***` — credentials are never printed. Self-host: set NOVADA_PROXY_USER/PASS (or let them auto-fetch from NOVADA_API_KEY) and fill the password from your environment. Hosted: take user/pass from dashboard.novada.com and use the returned host/port/username pattern.

**`type` guide:**
- `residential` — strongest anti-bot bypass, real home ISP IPs; escalate here when blocked
- `isp` — looks like a home user; best for social/ecommerce; ignores country param
- `datacenter` — fastest/cheapest; non-anti-bot, high-volume targets
- `mobile` — 4G/5G device IPs; mobile-targeted content and app APIs
- `static` — same dedicated ISP IP every request; set session_id + country explicitly for account-management workflows — omitting either silently falls back to a SHARED "default"/"us" identity, not an error
- `dedicated` — exclusive datacenter IP; set session_id explicitly for high-trust platforms — omitting it silently falls back to a SHARED "default" identity, not an error

**Escalation when blocked:** datacenter → isp → residential.
- **novada_verify** — Check whether a factual claim is supported by web sources. Runs 3 parallel searches (supporting, skeptical, fact-check angles) and returns a verdict: supported / unsupported / contested / insufficient_data.

**Best for:** checking claims before citing them, cross-validating findings, detecting misinformation.
**Not for:** open-ended questions (novada_research) or reading a specific URL (novada_extract).
**Note:** signal-based (search balance), not definitive. Confidence 0–100 indicates certainty.
- **novada_browser** — Interact with a web page — click, fill forms, scroll, screenshot, or run JavaScript. Chain multiple actions in one call.

**Best for:** login flows, paginated content, SPAs, form submission, visual verification, scraping behind interactions.
**Not for:** simple page reads (novada_extract), structured data (novada_scrape), raw HTML (novada_extract format="html").
**Actions:** navigate, click, type, screenshot, snapshot, aria_snapshot, evaluate, wait, scroll, hover, press_key, select — up to 20/call. snapshot = full DOM text; aria_snapshot = smaller semantic tree (prefer it for extraction).
**Sessions:** session_id reuses the same page (cookies, login) across calls — reliable only on the local/long-lived server; on hosted serverless, treat each call as one-shot. close_session releases early.
**Auth:** NOVADA_API_KEY auto-provisions Browser API credentials; NOVADA_BROWSER_WS optionally overrides.
**SPAs:** wait with domcontentloaded, never networkidle. `country` is accepted but not yet applied to the browser exit node — don't rely on it for geo-routing.
**Constraint:** close_session/list_sessions must be the ONLY action in the call.
- **novada_discover** — Lists all available Novada tools — name, description, category, group, and status. Useful at the start of a task to find the right tool, or whenever another tool's description isn't enough to decide between two options.

**Returns:** a markdown table grouped by category, plus a Tool Groups reference (core/scrapers/account/meta).
**Filter:** category narrows the catalog (e.g. category="Proxy"); NOVADA_GROUPS/NOVADA_TOOLS (local) or ?groups=/?tools= (hosted) narrow the actual tool set exposed on this connection.
**Status:** active = available now. Output includes server_version.

**Auth:** a single NOVADA_API_KEY authenticates search/extract/research/crawl/scrape/unblock/proxy auto-provisioning — no separate keys needed. NOVADA_BROWSER_WS/NOVADA_PROXY_ENDPOINT unlock extras, no extra key. See novada_account (section="summary") for balance/plans/entitlements.
- **novada_browser_flow** — Simplified browser automation — 5 actions (click, scroll, wait, type, screenshot). Use only if you need this simpler interface or novada_browser is unavailable.

**novada_browser is primary/more capable** — full CDP access, 12 action types + 2 session-management actions. Prefer it for new automation.
**Use this when:** you need the simplified flow API or have an existing workflow built on it.
**Actions:** click, scroll, wait, type, screenshot — up to 20/call.
**Sessions:** session_id reuses the browser instance (cookies, login) across calls; expires after 10 min idle.
**Not for:** reading one URL without interaction (novada_extract) or structured platform data (novada_scrape).
- **novada_ai_monitor** — Search PUBLIC indexed pages on AI-company domains (chatgpt.com/openai.com, perplexity.ai, anthropic.com, etc.) for brand mentions and sentiment. NOT page-change monitoring (novada_monitor) and does NOT query live AI models — a brand absent from indexed pages may still be discussed live; this only reflects indexed-page coverage.

**How it works:** for each selected domain group, runs a Google search scoped to that domain (e.g. site:openai.com "brandname") and analyzes snippets for sentiment, claims, and competitor co-mentions.
**Best for:** checking brand presence on AI-company public docs/blogs/changelogs.
**Not for:** live model answers about your brand (query the model directly), general web search (novada_search), real-time social monitoring (novada_scrape with twitter/instagram).
**Output:** per-domain sentiment (positive/neutral/negative), key claims from indexed snippets, competitor mentions, mention counts, source URLs.
**Domains:** chatgpt.com+openai.com, perplexity.ai, grok.com+x.com/i/grok, claude.ai+anthropic.com, gemini.google.com. Default: chatgpt, perplexity, grok.
- **novada_monitor** — Detect changes on a web page over time. Extracts content, computes a hash, and compares it with the previous check. Returns changed/unchanged plus field-level diffs.

**Use for:** e-commerce price monitoring, stock tracking, content-change detection, competitive pricing alerts.
**How:** the first call sets a baseline; later calls compare against it and report changes. Pass fields=["price","availability"] for field-level % diffs.
**Not for:** one-time extraction (novada_extract) or a full crawl (novada_crawl).
**Storage:** the "baseline" is an in-memory, process-local cache (keyed by URL) — never written to disk, a database, or any durable/external store, and never returned to or readable by any other caller. This is why readOnlyHint stays true despite the "write a baseline" language: nothing outside this process's own memory is touched.

⚠️ **Hosted endpoint (mcp.novada.com) limitation:** that in-memory cache does NOT survive between calls on hosted's serverless runtime — every call is a cold function with no prior state, so change detection always returns baseline_recorded. Use the local server (`npx novada-mcp`) or diff externally for real change detection.
- **novada_setup** — Onboarding and key-validation tool — useful at the start of a session, or whenever another tool reports a missing/invalid key.

**What it does:**
1. **Validates your key** — one cheap account read (wallet balance) confirms it works and shows your balance. No per-product probes, no credit cost.
2. **Guides you if keyless** — register at the Novada dashboard, copy your API key, get exact config snippets for Claude Code/Desktop/Cursor/VS Code/Windsurf.
3. **Orients you** — a plain-language list of core capabilities (search, extract, scrape, browser, account) plus add-ons.

**Reports one of 3 states:** valid key (ready) · invalid key (fix it) · no key (register). Output includes server_version.
**Auth-free by design:** a missing key never errors here — it guides, with a machine-usable agent_instruction for what to tell the user next.
**Unified key:** NOVADA_API_KEY covers search/extract/unblock/scraper/research/crawl/map/browser/proxy auto-provisioning. NOVADA_BROWSER_WS/NOVADA_PROXY_ENDPOINT are optional add-ons needing no separate key.
- **novada_account** — Single-call account & billing dashboard. Composes wallet balance, plan balances, capture logs, and health entitlements via the `section` param.

**Best for:** "what's my account status / balance" one-shot checks.
**section="summary" (default):** wallet balance + plan quotas + recent capture logs + product entitlements.
**section="balance":** master wallet currency balance.
**section="usage":** paginated transaction history (start_time/end_time/page/page_size).
**section="plans":** per-product plan balances (residential/isp/mobile/datacenter/static/capture); filter with products[].
**section="traffic":** daily proxy traffic consumption; filter with start_time/end_time/products[].
**Auth:** NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).
- **novada_proxy_account_create** — ⚠️ WRITE — Create a proxy sub-account. Two-step approval-token gate.

**Behavior:** call once WITHOUT `approval_token` to get a `confirmation_required` JSON preview (password masked) plus a fresh `approval_token` valid for 10 minutes — this does NOT hit the API. Show the preview to the human, then re-call with the EXACT SAME parameters plus that `approval_token` after explicit approval. `confirm: true` is a deprecated no-op and does NOT substitute for the token.

**Best for:** provisioning a team-member or per-project sub-account against your master plan.
**Params:** product ("1"=Residential, "2"=Rotating ISP, "3"=Rotating Datacenter, "4"=Unlimited, "7"=Unblocker, "9"=Mobile), account (3-64, [a-zA-Z0-9_-]), password (8-64), status ("1" active default | "-3" disabled), remark?, limit_flow? (GB cap), approval_token.
**Wire format:** multipart/form-data.
**Auth:** NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).
- **novada_proxy_account_list** — List proxy sub-accounts (wraps developer-api POST /v1/proxy_account/list).

**Best for:** auditing sub-accounts, finding account names before rotating credentials.
**Params:** product (REQUIRED — same codes as create), page, limit (max 200), status? ("1"|"-3"), account? (exact-match filter).
**Wire format:** multipart/form-data.
**Auth:** NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).
- **novada_ip_whitelist** — Manage the proxy IP whitelist — add/list/delete/remark — for Residential (1), Unlimited (4), and Static ISP (5).

**Actions:** "add" (WRITE, gated by approval_token), "list" (read-only), "del" (WRITE, gated by approval_token), "remark" (WRITE, gated by approval_token).
**Behavior for "add"/"del"/"remark":** call once WITHOUT `approval_token` to get a preview plus a fresh token (valid 10 minutes) — this does NOT hit the API. Re-call with the EXACT SAME parameters plus that token to execute. `confirm: true` is a deprecated no-op.
**Required:** action, product (1=Residential, 4=Unlimited, 5=Static ISP).
**Auth:** NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).
- **novada_capture_apikey** — Get or reset the Capture API key (wraps POST /v1/capture/get_apikey and /v1/capture/reset_apikey).

**Actions:** "get" = retrieve the current key (read-only). "reset" = regenerate it — DESTRUCTIVE, invalidates the old key, gated by a two-step approval_token.
**Behavior:** call "reset" once WITHOUT `approval_token` to get a warning preview plus a fresh token (valid 10 minutes) — this does NOT call the API. Re-call with the EXACT SAME parameters plus that token to execute. `confirm: true` is a deprecated no-op.
**Auth:** NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).
- **novada_static_ip_mgmt** — Manage static ISP IPs (wraps /v1/static_house/* developer-api endpoints).

**Actions:** "open" = purchase new IPs (WRITE, gated by approval_token). "renew" = renew existing IPs (WRITE, gated by approval_token). "export"/"list" = read-only.
**Behavior:** call "open"/"renew" once WITHOUT `approval_token` to get a preview plus a fresh token (valid 10 minutes) — this does NOT hit the API. Re-call with the EXACT SAME parameters plus that token to execute. `confirm: true` is a deprecated no-op.
**Auth:** NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).
- **novada_session_stats** — Per-process / per-session usage telemetry: tool-call counts, the last-N calls, and process uptime.

**Best for:** "what have I called this session?" / debugging an agent loop / seeing which tools dominate usage.
**Returns:** session_started, uptime, total_calls, per-tool counts (high→low), most-recent calls (newest first, capped by recent_limit).
**Scope:** in-memory, per-process — resets on restart. Nothing persists or leaves the process. Auth-free.
- **novada_search_feedback** — Record search-result quality so future ranking can learn from it. Returns a thank-you/echo confirmation with an agent_instruction.

**Best for:** after a novada_search call, report which result URLs were useful and rate the set (good/ok/bad) — biases future ranking.
**Params:** search_id (prior search's id), query, rating ('good'|'ok'|'bad'), useful_urls? (max 50), note? (what was missing).
**Scope:** in-memory, per-process — resets on restart. Nothing persists. Auth-free.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "novada-mcp": {
    "command": "npx",
    "args": ["-y","novada-mcp"],
    "env": {
      "NOVADA_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `NOVADA_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What novada-mcp does

novada-mcp gives MCP-compatible agents access to web search, page extraction, structured platform scrapers, crawling, site mapping, browser automation, proxy routing, claim verification, and monitoring. It is aimed at search and data extraction tasks that would otherwise require several separate services or custom HTML parsers.

The platform-specific tools return structured records rather than forcing an agent to interpret raw pages. Supported sources include Amazon, Google, Bing, DuckDuckGo, Yandex, YouTube, Instagram, Facebook, TikTok, X, Walmart, LinkedIn, GitHub, and Perplexity. Operations are typed per platform, so invalid operation names can be rejected before a network request.

## How it works

`novada_search` finds pages through Google, DuckDuckGo, or Yandex and returns titles, URLs, snippets, and relevance ordering. `novada_extract` reads a known URL and can process up to 10 URLs in parallel. It can return Markdown, HTML, or structured JSON fields such as price, title, author, and date. Rendering normally starts with a static request and escalates to JavaScript or browser access when required.

For broader jobs, `novada_research` runs multiple searches, removes duplicates, extracts leading sources, and returns numbered passages for the agent to use when composing an answer. `novada_map` discovers site URLs, while `novada_crawl` retrieves a bounded set of related pages inline. `novada_site_copy` is intended for larger documentation or knowledge-base copies and writes one Markdown file per page with a manifest.

The scraper tools call Novada’s scraper API and provide structured records in formats including Markdown tables, JSON, TOON, CSV, Excel, and HTML. `novada_proxy` supplies proxy configuration for requests made by the caller. Browser tools support actions such as navigation, clicking, typing, scrolling, screenshots, DOM snapshots, and JavaScript evaluation.

## Setup and configuration

The hosted endpoint is available at `https://mcp.novada.com/mcp`. Hosted connections authenticate with OAuth or an `Authorization: Bearer` header; the API key is not accepted in a URL. Self-hosting uses the npm package through `npx -y novada-mcp` and can be configured for clients such as Claude Code, Cursor, Windsurf, and VS Code.

Set `NOVADA_API_KEY` for authenticated search, extraction, research, crawling, scraping, proxy provisioning, and related features. `NOVADA_BROWSER_WS` can provide an alternate browser connection, and `NOVADA_PROXY_ENDPOINT` enables an optional proxy endpoint. The `novada_setup` tool validates a key, reports its balance, and provides onboarding guidance when no key is available. Usage is billed to the Novada account, with free credits available when starting an account.

## Tools and capabilities

- Search and rank web results with domain, time, and geographic filters.
- Extract one or several pages with automatic anti-bot escalation and selectable output formats.
- Research a question across multiple sources and return numbered citations.
- Scrape typed records from 14 supported platforms, including commerce, social, search, video, jobs, and repository data.
- Discover site URLs, crawl up to 20 related pages, or copy larger sites to local Markdown files.
- Automate browser sessions, route requests through selected proxy types, verify claims, and monitor page changes.

The tool choice matters: use extraction for a known URL, mapping for URL discovery, crawling for a small related set, and site copy for a larger local corpus. Platform scrapers are preferable when the target source has a dedicated operation and structured fields are needed.

## Limitations and notes

`novada_crawl` is capped at 20 pages, while `novada_map` returns at most 100 URLs. `novada_site_copy` supports up to 1,000 pages and returns a manifest path rather than page bodies inline. Research extracts full content only from its top five sources and bounds each source’s size.

Browser sessions can be reused with a session ID on a local or long-lived server. Hosted serverless calls should be treated as one-shot for session reliability. The browser’s `country` parameter does not currently control its exit location. Page monitoring stores its baseline only in process memory, so hosted serverless execution cannot reliably compare separate calls; local execution or external diffing is required for persistent change detection.

_Full upstream README: https://allmcps.com/mcp/novada-mcp/readme_