Skip to main content
Glama
ZapFetch MCP Server

ZapFetch MCP Server

by zapfetch

@zapfetchdev/mcp-server

MCP (Model Context Protocol) server for ZapFetch — APAC-native web scraping API for AI agents.

Use ZapFetch directly from Claude Desktop, Cursor, Windsurf, and any other MCP-compatible client.

Tools

  • zapfetch_scrape — scrape a single URL

  • zapfetch_search — web search with optional content extraction

  • zapfetch_crawl — crawl a website (async, returns job_id)

  • zapfetch_crawl_status — poll crawl job progress

  • zapfetch_map — discover URLs on a site (fast, no content)

  • zapfetch_extract — extract structured data with a prompt + schema

  • zapfetch_extract_status — poll extract job progress

Docs: https://docs.zapfetch.com

For docs lookups, Claude/Cursor/Windsurf can also use the auto-generated Mintlify MCP at https://docs.zapfetch.com/mcp.

Related MCP server: multi-scraper-mcp

Prerequisites

Install

npm install -g @zapfetchdev/mcp-server

Configure

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "zapfetch": {
      "command": "npx",
      "args": ["-y", "@zapfetchdev/mcp-server"],
      "env": {
        "ZAPFETCH_API_KEY": "zf-your-api-key"
      }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "zapfetch": {
      "command": "npx",
      "args": ["-y", "@zapfetchdev/mcp-server"],
      "env": { "ZAPFETCH_API_KEY": "zf-your-api-key" }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "zapfetch": {
      "command": "npx",
      "args": ["-y", "@zapfetchdev/mcp-server"],
      "env": { "ZAPFETCH_API_KEY": "zf-your-api-key" }
    }
  }
}

Install via Smithery

For a one-command install that auto-writes the config for your MCP client:

npx -y @smithery/cli install @zapfetchdev/mcp-server --client claude
# or --client cursor, --client windsurf

Smithery will prompt for your ZapFetch API key once, then register the server in the right config file for you. This invokes the package's STDIO entry (bin.zapfetch-mcp → dist/index.js) — identical to the manual configs above.

Environment Variables

Variable

Required

Default

Description

ZAPFETCH_API_KEY

STDIO

—

Your ZapFetch API key (STDIO mode only — HTTP mode takes the key per-request via Authorization: Bearer)

ZAPFETCH_API_URL

no

https://api.zapfetch.com

Override for self-host / dev

PORT

HTTP

3000

HTTP server port (HTTP mode only)

ZAPFETCH_TRANSPORT

Docker

stdio

Inside the Docker image only, switches between stdio / http via entry.sh. Ignored by the zapfetch-mcp / zapfetch-mcp-http npm binaries.

Usage Examples

After configuration, ask your AI assistant naturally — it will pick the right tool automatically.

Scrape a single page

"Scrape https://rakuten.co.jp and give me the main content as markdown."

Uses zapfetch_scrape. Best for a known URL where you want raw page content quickly. If the page is geo-blocked or returns sparse content, follow up with a search instead.

Search the web

"Find the top 5 recent blog posts about TypeScript 5.7 and summarize each one."

Uses zapfetch_search. Returns ranked results with optional content extraction. Useful when you don't have a specific URL yet, or as a fallback when a direct scrape comes up empty.

Crawl a site (multi-page)

"Crawl https://docs.example.com starting from the root, up to 50 pages, and summarize the authentication section."

Uses zapfetch_crawl to kick off an async job (returns a job_id), then zapfetch_crawl_status to poll until complete. The assistant handles the polling loop — you just wait for the result.

Tip: For large sites, map first (see below) to identify which URLs are worth crawling before committing.

Map a site (URL discovery)

"List all URLs under https://docs.example.com/api so I can decide which pages to scrape."

Uses zapfetch_map. Returns URLs only — no content fetched — so it's fast even on large sites. Pair with zapfetch_scrape to cherry-pick the pages you actually need:

"Map https://stripe.com/docs, then scrape the 3 pages most relevant to webhook setup."

Extract structured data

"Extract product name, price, currency, and stock status from these 5 rakuten.co.jp product URLs. Return as a JSON array."

Uses zapfetch_extract with a prompt and optional JSON schema. The job is async — zapfetch_extract_status polls it to completion. Good for turning arbitrary product pages, job listings, or articles into structured records at scale.

Poll extract job status

"Check whether the extract job job_abc123 is done."

Uses zapfetch_extract_status directly. You rarely need to ask for this by name — the assistant calls it automatically after zapfetch_extract — but it's useful if you started a job in a previous session and want to retrieve results later.

Combining tools

Tools compose naturally. A few common patterns:

  • Survey then scrape: map a large site to get all URLs, filter to the relevant ones, scrape each.

  • Search then scrape: search to find the canonical source for a topic, then scrape that page for full content.

  • Scrape with fallback: if zapfetch_scrape returns thin content (e.g. JS-heavy page), the assistant can fall back to zapfetch_search to find a cached or mirror version.

Migrating from Firecrawl MCP

ZapFetch is Firecrawl-compatible at the API level, but this MCP uses zapfetch_* tool names (not firecrawl_*) to avoid conflicts if you run both. Capabilities are 1:1 — just update prompts referring to tool names.

HTTP transport (self-hosted)

For hosted / multi-tenant deployments, run the HTTP server instead of STDIO. Each request carries its own API key via Authorization: Bearer, so a single deployment can serve many users without sharing credentials.

Docker

docker run -d \
  -p 3000:3000 \
  -e ZAPFETCH_TRANSPORT=http \
  docker.io/zapfetchdev/mcp:latest

From npm

npm install -g @zapfetchdev/mcp-server
# then run the HTTP entry (never the STDIO one in this mode)
zapfetch-mcp-http

Endpoints

Path

Auth

Behavior

GET /health

none

Returns {ok:true, version, transport:"http"}. Use for container health checks.

POST /mcp

Authorization: Bearer <key> required

MCP JSON-RPC endpoint. Requests MUST include Accept: application/json, text/event-stream per MCP spec.

Example call

curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer fc-YOUR-KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Security notes

  • Do not set ZAPFETCH_API_KEY in HTTP mode. The server refuses to start (exit code 2) if the env var is present — this prevents a misconfigured container from silently serving every request from the operator's key.

  • The HTTP server is stateless: each request builds its own transport + client, with the Bearer token flowing to the MCP tool handler via the SDK's native extra.authInfo.token channel. No cross-request state, no session leaks.

  • Upstream ZapFetch API error strings are sanitized before transiting to HTTP clients — only a small allowlist of error codes (rate_limit, invalid_key, quota_exceeded, upstream_unavailable) passes through.

  • The stderr access log is strict-allowlist: only ts / method / path / status / ms / origin_ip. Bearer tokens, bodies, and headers are never logged.

Development

pnpm install        # or npm install
npm run typecheck
npm run build       # -> dist/

Local test with Claude Desktop pointed at your build:

{
  "mcpServers": {
    "zapfetch-dev": {
      "command": "node",
      "args": ["/absolute/path/to/zapfetch-mcp/dist/index.js"],
      "env": { "ZAPFETCH_API_KEY": "zf-..." }
    }
  }
}

License

MIT

Available Tools

7 tools
zapfetch_crawlA

Crawl a website and extract content from multiple pages. Use this when the user wants to gather content from an entire site or section. Returns a job_id for async polling. Long-running — consider asking the user before invoking if the site is large. For a single page, use zapfetch_scrape. For URL discovery only (no content), use zapfetch_map.

Inputs: url (required), limit, maxDiscoveryDepth, includePaths, +2 more.

zapfetch_crawl_statusA

Check the status of a running crawl job. Returns 'scraping' (in progress) or 'completed'/'failed'/'cancelled' (done). When status=completed, returns all crawled page content. Poll every 2-5 seconds until done.

Inputs: job_id (required).

zapfetch_extractA

Extract structured data from one or more URLs using natural language prompt + optional JSON schema. Use this when the user wants JSON-shaped data (not markdown), especially across multiple pages with the same structure (e.g. product listings, job postings, article metadata). Returns a job — poll with zapfetch_extract_status.

Inputs: urls (required), prompt (required), schema.

zapfetch_extract_statusA

Check the status of a running extract job. Returns 'processing' (in progress) or 'completed'/'failed'/'cancelled' (done). When status=completed, returns the extracted structured data for all input URLs. Poll every 2-5 seconds until done.

Inputs: job_id (required).

zapfetch_mapA

Discover all URLs on a website without crawling content. Fast — use this to survey a site before deciding what to crawl. Returns list of URLs, optionally with titles/descriptions. Much cheaper than zapfetch_crawl (no content extraction). Use zapfetch_scrape or zapfetch_crawl on specific URLs from the result.

Inputs: url (required), search, limit, sitemap.

zapfetch_scrapeA

Scrape a single web page. Use this when the user wants to extract the content of ONE specific URL. Returns clean markdown (and other formats) of the page content. For crawling multiple URLs on a site, use zapfetch_crawl instead.

Inputs: url (required), formats, onlyMainContent, waitFor, +2 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: crawling multiple pages (zapfetch_crawl), checking crawl status (zapfetch_crawl_status), structured extraction (zapfetch_extract, zapfetch_extract_status), URL discovery (zapfetch_map), single-page scraping (zapfetch_scrape), and web search (zapfetch_search). Descriptions explicitly contrast them, eliminating ambiguity.

    Naming Consistency4/5

    Tool names follow a consistent prefix 'zapfetch_' with verb_noun pattern for actions (crawl, crawl_status, extract, extract_status, map, scrape, search). Minor inconsistency: 'crawl' vs 'crawl_status' and 'extract' vs 'extract_status' use a suffix, while others are single verbs. Still highly predictable.

    Tool Count5/5

    Seven tools cover the core web scraping and search functionality without redundancy. Each tool serves a unique purpose, and the count is appropriate for the domain. Not too few nor too many.

    Completeness5/5

    The tool set covers a complete workflow: discover URLs (zapfetch_map), scrape single pages (zapfetch_scrape), crawl multiple pages (zapfetch_crawl), extract structured data (zapfetch_extract), search the web (zapfetch_search), and poll async jobs (zapfetch_crawl_status, zapfetch_extract_status). No obvious gaps for common web scraping tasks.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides 42+ MCP tools for browser automation, web scraping, and search, enabling AI agents like Claude and Cursor to browse, extract data, and run research agents on the live web.
      8
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables lead generation and web scraping through 16 MCP tools, allowing AI clients like Claude, Cursor, and Windsurf to perform scraping tasks via natural language.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to scrape web pages into Markdown, text, HTML, JSON, PDFs, screenshots, and structured data, while managing batch scraping jobs, persistent browser sessions, usage/request history, and docs lookup through native MCP tools.
      27
      415 npm
      3
      Apache 2.0