Optional web search backend for the search tool, configured via [BRAVE](/mcp/servers/integrations/brave)_API_KEY to use Brave Search.
Default web search backend for the search tool, providing privacy-focused search results without requiring additional configuration.
Alternative local LLM backend for the extract and deep_research tools, allowing use of self-hosted models (e.g., Qwen) via SCRAPER_[OLLAMA](/mcp/servers/integrations/ollama)_HOST and model environment variables.
Optional self-hosted web search backend for the search tool, configurable via SCRAPER_[SEARXNG](/mcp/servers/integrations/searxng)_URL to use a SearXNG instance.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Web Scraper MCP Scrape https://example.com and summarize it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A self-hosted Model Context Protocol server for reading public web pages, bounded crawling, search, model-backed extraction and browser interaction. Supports Python 3.11–3.13 and stdio or authenticated HTTP.
Run it with your own models and infrastructure. Fetching is static by default; browser rendering is optional and uses sandboxed Chromium with guarded egress.
Tool | Behavior |
| Fetch a public URL and return its title, Markdown and optional capped links or HTML. |
| Start a background crawl with page/depth limits and an optional same-host policy. |
| Read progress/results or cancel a job while retaining completed pages. |
| Return canonical, deduplicated links; defaults to the source host. |
| Create or reuse a browser session and return an ARIA snapshot. |
| Click, fill, press, select or wait using a selector. Explicit actions may submit same-origin forms. |
| Close a session and release its page capacity. |
| Use Tavily, Brave, SearXNG or DuckDuckGo, in that priority order. |
| Ask Ollama or Anthropic for text or data matching a locally validated JSON Schema. |
| Search, read bounded sources and synthesize a report with checked citation indices and source failures. |
Related MCP server: Universal Web Data Extraction Platform
Install Python 3.11–3.13 and uv, then:
git clone https://github.com/Prog-up/web-scraper-mcp.git
cd web-scraper-mcp
uv sync --frozen
cp .env.example .envFor a local MCP client using stdio:
SCRAPER_TRANSPORT=stdio uv run --frozen web-scraper-mcpStdio does not require a token. Clients with an mcpServers configuration can use:
{
"mcpServers": {
"web-scraper": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/web-scraper-mcp", "run", "--frozen", "web-scraper-mcp"],
"env": {"SCRAPER_TRANSPORT": "stdio"}
}
}
}For HTTP:
export SCRAPER_AUTH_TOKEN=$(openssl rand -hex 32)
./start.shConnect to http://127.0.0.1:8000/mcp with
Authorization: Bearer YOUR_TOKEN. Keep the token in your client's secret
configuration. HTTP startup rejects missing or blank tokens. The launcher stays
in the foreground; use a service manager for supervision.
Scraping and browser tools do not require an LLM. For extract and
deep_research, configure an installed Ollama model and reachable endpoint in
.env, or select Anthropic and supply its API key. Search defaults to DuckDuckGo;
other providers are optional. See configuration and
the environment template.
For sandboxed rendering and browser sessions:
export SCRAPER_AUTH_TOKEN=$(openssl rand -hex 32)
docker compose up --buildCompose runs the app on an internal network with a separate guarded egress proxy, a read-only filesystem, resource limits and Chromium's sandbox enabled. Use Docker Engine 28 or newer and a host that supports unprivileged user namespaces. Sandbox startup failures stop rendering; there is no automatic fallback that disables the sandbox.
Compose does not start Ollama. Its model endpoint must be reachable from the isolated app network; an external endpoint needs a trusted route or relay. See deployment for static-only containers, networking, model connectivity and browser restrictions, and seccomp provenance.
Intended for public HTTP(S) pages. Private destinations are denied by default. Error status pages and unsupported content types are rejected.
Protected websites, CAPTCHAs and some JavaScript applications may fail. There is no managed proxy pool or guaranteed challenge bypass.
Browser sessions block downloads, WebSockets, service workers and background writes. Explicit actions allow writes only to the current page origin.
Crawl jobs and browser sessions live in memory. They expire and are lost on restart; this is not a durable distributed job system.
One HTTP bearer token grants all tools. There are no per-user quotas or tenant isolation; use TLS and trusted access boundaries beyond localhost.
JSON Schema validation checks output structure. Citation validation checks source indices, not whether a source supports every claim. Review important extracted facts against the original sources.
Self-hosting still requires maintenance and compute. Configured search/model providers receive their requests; provider fees and policies apply.
See CONTRIBUTING.md for setup and checks, benchmarks for reproducible measurements, and SECURITY.md for vulnerability reporting and security boundaries.
CI checks Python 3.11–3.13, lint, formatting, typing, tests, secrets and locked dependencies. Container releases also test the exact sandboxed browser artifact, scan vulnerabilities, and sign the published digest with an SPDX SBOM. See release procedures, release history and the known security exceptions for 1.1.0 and 1.1.1.
Report bugs through GitHub issues. Support is community-based, with no service-level agreement.
See LICENSE for the existing GNU GPL version 3 terms.
Search the web, read the top sources, and return a cited synthesis report.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The research question. | |
| max_sources | No | How many top results to read. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the general workflow (searching the web, reading top sources, producing a cited report) but does not mention read-only behavior, potential latency, rate limits, or any limitations. The description is truthful and somewhat informative, but leaves important operational behavior unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with a clear chronological structure, no filler, and immediate front-loading of the core action ('Search the web'). Every phrase earns its place: 'read the top sources' and 'cited synthesis report' are distinct and necessary components. This is appropriately concise for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the two fully documented parameters and the presence of an output schema (likely covering the report structure), the description covers the essential process and outcome well. What is missing is more explicit context about when to use the tool versus siblings and a few behavioral notes, but the combination of description and schema is largely sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both 'query' and 'max_sources' have descriptions in the schema. The tool description's phrasing ('research question', 'top results') mirrors the schema descriptions without adding new meaning about formats, constraints, or interpretation. This meets the baseline of 3 but does not exceed what structured data already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb sequence ('Search', 'read', 'return') with a clear deliverable ('a cited synthesis report'). It unambiguously identifies the tool's function and naturally distinguishes deep_research from siblings like search (just web results) or scrape/extract (page-level content gathering). The multi-step process is explicit and not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for comprehensive research with cited synthesis, but it never explicitly states when to prefer this over search, scrape, or extract, nor does it give any 'instead of' guidance. Context makes the intended use reasonably clear, yet there are no exclusions or alternative routing as seen in higher-quality definitions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract structured data (JSON matching json_schema) or a text answer from a page.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to extract from. | |
| prompt | No | Natural-language extraction instruction. | |
| render | No | Force a browser render. | |
| json_schema | No | JSON Schema describing the fields to extract (recommended). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It does disclose the two operating modes (structured JSON versus text answer), which is meaningful. However, it does not mention rendering defaults, page-fetch behavior, rate limits, or side effects. The render parameter is defined in the schema, so some of that context is available, but the description itself stays minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It could be slightly better structured by explicitly separating the two modes, but as written it is efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists, so return-value details are covered elsewhere, and the input schema is fully documented. The main gaps are the lack of choice guidance between prompt and json_schema, and no indication of when to use extract instead of scrape. These gaps make the description adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already defines url, prompt, render, and json_schema. The description adds a high-level mapping by linking json_schema to structured JSON and implying the text answer comes from the prompt, but it does not add much beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('extract'), the target resource ('a page'), and the two possible outputs: JSON matching json_schema or a text answer. It does not explicitly distinguish itself from sibling tools like scrape or search, though the verb and output specification make the core purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use extract versus scrape, search, or deep_research, and no exclusions or conditions. The only context is 'from a page,' which is too thin to help an agent choose between this and its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scrape a single URL into clean markdown (boilerplate/ads stripped).
Tries a fast static fetch first and falls back to a stealth headless browser automatically when the page looks JS-gated.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL to scrape (http/https). | |
| render | No | Force a headless browser render (for JS-heavy pages). | |
| include_links | No | Also return all links found on the page. | |
| include_raw_html | No | Also return the raw HTML (large). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It clearly reveals the two-phase fetch strategy, the automatic fallback to headless browsing, and the output transformation to clean markdown. It does not discuss rate limits, authentication, or failure behavior, but the core operational traits are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff, front-loading the primary purpose before the fallback behavior. Every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of an output schema means return values do not need to be explained in the description. Combined with fully documented parameters and a clear explanation of the scraping strategy, the definition is largely complete, though it omits failure semantics and any rate-limit or authentication caveats.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already documented in the input schema. The tool description adds no additional parameter-level meaning, which matches the baseline for fully-covered schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Scrape a single URL') and a concrete outcome ('into clean markdown'), making the tool's purpose immediately clear. The boilerplate/ads-stripping detail further distinguishes it from general fetch or research siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains that a fast static fetch is attempted first and that a stealth headless browser is used automatically for JS-gated pages, giving clear context on when the tool adapts. It does not explicitly name alternatives or say when to prefer sibling tools, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Web search. Returns ranked results (title, url, content snippet).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query. | |
| max_results | No | Max results. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden. It does communicate the read-only nature implicitly by saying 'Returns', but it doesn't disclose rate limits, result freshness, error behavior, or whether any resources are modified. This is additional but minimal context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence front-loads the primary action and return format. No filler words; the description is appropriately sized and every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with a complete input schema and an output schema, the description is largely sufficient. It identifies what the tool returns and the parameters are well covered by the schema. It lacks any mention of when to use it relative to deep_research, but that falls under usage guidance rather than completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with descriptions for both query and max_results. The tool description adds no parameter-level information beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair ('Web search') and specifies the return shape (ranked results with title, url, content snippet). This clearly distinguishes it from sibling tools like scrape, extract, and deep_research without needing to open their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to choose search over its siblings, nor any exclusions or alternative recommendations. The presence of deep_research, scrape, and extract in the same toolset makes this omission a real gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0deep_researchextractscrapesearchScored across 4 tools
scrape and extract both operate on a page but are clearly distinguished by output type: markdown document vs structured JSON/answer. search and deep_research are also distinct, though deep_research could be seen as a superset of search.
All tools use lowercase snake_case imperative verbs: scrape, extract, search, deep_research. The naming pattern is consistent and predictable.
Four tools is well-scoped for a web scraper/research server: one for raw page content, one for structured extraction, one for search, and one for synthesis. Each tool has a clear purpose with no redundant bloat.
The core web research workflow is covered: search, fetch, extract, and synthesize. A minor gap is the lack of batch crawling or link-following features, but most common agent tasks can be completed with these tools.
Web scraping for AI agents: scrape, search, crawl, map any website to markdown + JSON. No browser.
Live web access for agents: scrape, SERP search, crawl/map, 100+ collectors, datasets, proxies.
Enable language models to perform advanced AI-powered web scraping with enterprise-grade reliabili…
Web scraping for agents. Point it at a URL and it returns the page as clean markdown, JavaScript-rendered pages included. Point it at a site and it maps the URLs or crawls the section you need in the background, a few pages at a time so results fit in the conversation. Search the web and read full pages, extract fields with a JSON schema you define (validated, never invented), read a store's catalogue or a blog's posts from the platform's own feed, and check whether a page has changed. Failed requests cost nothing. The free plan includes 1,500 credits a month.
