fetcher.sh MCP Server

Official Model Context Protocol server for fetcher.sh — web data API for AI agents and applications.

Connect Claude Desktop, Cursor, VS Code Copilot, or any MCP client to fetcher.sh and search tweets, YouTube videos, Reddit threads, Google results, app-store listings, and more — all from natural language.

Features

Five catalog tools, mapped to the hosted server at mcp.fetcher.sh. Discovery is local (no network); paid fetches hit the live REST API.

| Tool | Cost | What it does | |---|---|---| | search_endpoints | free | Keyword / service search over 111 endpoints across 11 APIs | | describe_endpoint | free | Parameters, allowed values, price, response shape | | fetch_data | paid | Run any catalog path: { path, params } | | check_balance | free | Credits left on FETCHER_API_KEY | | topup_credits | — | Returns the prepaid top-up URL (minimum $1) |

Set FETCHER_SERVICE=twitter (or youtube, reddit, …) to switch to a specialized server: one named tool per endpoint of that service, plus the two credit tools.

Quick Start

1. Get an API key

Top up at fetcher.sh/topup — a bby_live_… key is minted with the first credit purchase. There is no account or OAuth step.

2. Configure your MCP client

Claude Desktop

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

{
  "mcpServers": {
    "fetcher": {
      "command": "npx",
      "args": ["-y", "@fetcher-sh/mcp-server"],
      "env": {
        "FETCHER_API_KEY": "bby_live_..."
      }
    }
  }
}

Restart Claude Desktop. The catalog tools will be available in any chat — Claude will pick the right one based on your prompt.

Cursor

Open Settings → MCP → Add new MCP Server:

{
  "mcpServers": {
    "fetcher": {
      "command": "npx",
      "args": ["-y", "@fetcher-sh/mcp-server"],
      "env": {
        "FETCHER_API_KEY": "bby_live_..."
      }
    }
  }
}

VS Code (Copilot Chat with MCP)

Add to your MCP servers config — same shape as Claude Desktop / Cursor.

Claude Code

claude mcp add fetcher npx -- -y @fetcher-sh/mcp-server -e FETCHER_API_KEY=bby_live_...

3. Use it

In any MCP-enabled chat:

"Find recent tweets from @OpenAI about agents in the last week"

"Search YouTube for lofi streams uploaded this week"

"What are the top Reddit posts about stablecoin payments?"

The client will pick search_endpoints → describe_endpoint → fetch_data (or a named service tool if FETCHER_SERVICE is set).

Authentication

Authentication is via the FETCHER_API_KEY environment variable, injected by your MCP client. The server never stores or logs the key. Each paid call sends the key as Authorization: Bearer to https://fetcher.sh.

search_endpoints and describe_endpoint work without a key — they read the bundled catalog.

Optional env vars:

| Variable | Purpose | |---|---| | FETCHER_API_KEY | Prepaid bby_live_… key | | FETCHER_SERVICE | Restrict to one service slug (twitter, youtube, …) | | FETCHER_API_BASE | Override the API origin (default https://fetcher.sh) |

Hosted Streamable HTTP (no install) is also available at https://mcp.fetcher.sh — that surface accepts the same Bearer key, or per-call USDC via x402.

Pagination

List endpoints (followers, replies, search results, comments, …) accept a cursor parameter and return a next_cursor (or cursor) field. Pass it back on the next call to page through.

Error handling

• 429 / 5xx responses are automatically retried with exponential backoff (3 attempts, 1s / 2s / 4s)
• Network timeouts: 30s per request
• 4xx errors (other than 429) surface immediately to the model with the original message
• Unknown paths and missing required parameters are rejected before any charge

Tools — full spec

Each tool's input schema is exposed via MCP's tools/list and follows JSON Schema. Browse interactively:

npx @modelcontextprotocol/inspector npx -y @fetcher-sh/mcp-server

What's NOT included

By design, this server exposes read-only public data. The following are intentionally excluded:

• Posting, liking, following, DMs, or any write action on the underlying platforms
• Official platform developer accounts / OAuth
• Account login or 2FA
• Per-call wallet payment (x402) on this stdio transport — use mcp.fetcher.sh or fetcher.sh/topup for that

Spec compliance

• Built on @modelcontextprotocol/sdk v1
• Targets MCP spec 2025-11-25
• Transport: stdio (hosted Streamable HTTP lives at https://mcp.fetcher.sh)
• Tested with: mcp-inspector, Claude Desktop, Cursor, Claude Code

Development

git clone <this-repo>
cd fetcher-mcp-server
npm install
npm run build
npm test
FETCHER_API_KEY=bby_live_... npm run inspect

Links

• fetcher.sh — REST API homepage
• API docs
• Top up credits
• Hosted MCP
• Model Context Protocol

License

MIT © fetcher.sh