# fetcher.sh MCP Server

[![npm version](https://img.shields.io/npm/v/@fetcher-sh/mcp-server.svg)](https://www.npmjs.com/package/@fetcher-sh/mcp-server)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![MCP Spec 2025-11-25](https://img.shields.io/badge/MCP-2025--11--25-green)](https://modelcontextprotocol.io/specification)

Official [Model Context Protocol](https://modelcontextprotocol.io) server for **[fetcher.sh](https://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](https://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](https://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):

```json
{
  "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:

```json
{
  "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

```bash
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:

```bash
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](https://mcp.fetcher.sh) or [fetcher.sh/topup](https://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

```bash
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](https://fetcher.sh) — REST API homepage
- [API docs](https://fetcher.sh/docs)
- [Top up credits](https://fetcher.sh/topup)
- [Hosted MCP](https://mcp.fetcher.sh)
- [Model Context Protocol](https://modelcontextprotocol.io)

## License

MIT © fetcher.sh