scavio-mcp

# Scavio MCP Server

![GitHub Repo stars](https://img.shields.io/github/stars/scavio-ai/scavio-mcp?style=social)
![License](https://img.shields.io/github/license/scavio-ai/scavio-mcp)

[Scavio](https://scavio.dev) is a unified [Web Search API](https://scavio.dev/docs/search-api) and MCP server that gives AI agents web search, page extraction, and structured data from e-commerce, social, travel, jobs, real-estate, app-store, ad-library and company-filing sources. 191 tools across 31 platforms plus Extract, one API key.

**The 22 platforms added in 0.13.0 are opt-in.** Registering all 191 tools puts 136KB of tool definitions — roughly 35k tokens — into every session before you type anything. So the default is the surface 0.12.x already had, plus Extract: 106 tools, 63KB. Upgrading never removes a tool you were using. Everything else is one env var away: see [Choosing which tools load](#choosing-which-tools-load).

## Remote MCP Server

Connect directly to Scavio's remote MCP server without any local installation:

```
https://mcp.scavio.dev/mcp
```

Two ways to authenticate:

- **Sign in with OAuth, no key to copy.** Claude Desktop, claude.ai and Claude Code sign in to your Scavio account through the server. In Claude Desktop or claude.ai: Settings > Connectors > Add custom connector, name it Scavio, paste the URL, then Connect and Authorize. In Claude Code: `claude mcp add --transport http scavio https://mcp.scavio.dev/mcp`, then run `/mcp` and choose Authenticate.
- **API key.** Pass it in the `x-api-key` header. Get your key at [scavio.dev](https://scavio.dev).

---

## Run Locally (npx)

Prefer to run the server on your own machine? Use `npx` with no clone or build. The server runs over stdio and only needs your `SCAVIO_API_KEY`.

### Claude Code

```bash
claude mcp add scavio -e SCAVIO_API_KEY=YOUR_SCAVIO_API_KEY -- npx -y @scavio/mcp-server
```

### Any MCP-Compatible Client (Claude Desktop, Cursor, Windsurf, VS Code, etc.)

```json
{
  "mcpServers": {
    "scavio": {
      "command": "npx",
      "args": ["-y", "@scavio/mcp-server"],
      "env": {
        "SCAVIO_API_KEY": "YOUR_SCAVIO_API_KEY"
      }
    }
  }
}
```

Requires Node.js 20+. Get your API key at [scavio.dev](https://scavio.dev).

---

## Install

### Claude Code

Sign in with OAuth, then run `/mcp` inside Claude Code and choose Authenticate:

```bash
claude mcp add --transport http scavio https://mcp.scavio.dev/mcp
```

Or pass an API key:

```bash
claude mcp add --transport http scavio https://mcp.scavio.dev/mcp --header "x-api-key: YOUR_SCAVIO_API_KEY"
```

### Claude Desktop

No API key needed: Settings > Connectors > Add custom connector, name it Scavio, paste `https://mcp.scavio.dev/mcp`, then Connect and sign in to your Scavio account. The same steps work on claude.ai.

Or run the server locally. Add to `claude_desktop_config.json` (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "scavio": {
      "command": "npx",
      "args": ["-y", "@scavio/mcp-server"],
      "env": {
        "SCAVIO_API_KEY": "YOUR_SCAVIO_API_KEY"
      }
    }
  }
}
```

Requires Node.js 20+. Restart Claude Desktop after saving.

### Cursor

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=scavio&config=eyJ1cmwiOiJodHRwczovL21jcC5zY2F2aW8uZGV2L21jcCIsImhlYWRlcnMiOnsieC1hcGkta2V5IjoiWU9VUl9TQ0FWSU9fQVBJX0tFWSJ9fQ%3D%3D)

Or add to `.cursor/mcp.json` in your project root or `~/.cursor/mcp.json` for global:

```json
{
  "mcpServers": {
    "scavio": {
      "type": "http",
      "url": "https://mcp.scavio.dev/mcp",
      "headers": {
        "x-api-key": "YOUR_SCAVIO_API_KEY"
      }
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "scavio": {
      "type": "http",
      "url": "https://mcp.scavio.dev/mcp",
      "headers": {
        "x-api-key": "YOUR_SCAVIO_API_KEY"
      }
    }
  }
}
```

### VS Code

Create `.vscode/mcp.json` in your project root:

```json
{
  "servers": {
    "scavio": {
      "type": "http",
      "url": "https://mcp.scavio.dev/mcp",
      "headers": {
        "x-api-key": "YOUR_SCAVIO_API_KEY"
      }
    }
  }
}
```

### ChatGPT

1. Go to [ChatGPT](https://chatgpt.com) > **Settings** > **Apps & Connectors**
2. Click **Add custom connector**
3. Enter the MCP server URL: `https://mcp.scavio.dev/mcp`
4. Configure authentication with your API key

### Cline

Add to `cline_mcp_settings.json` (open via Cline sidebar > MCP Servers > Configure):

```json
{
  "mcpServers": {
    "scavio": {
      "type": "http",
      "url": "https://mcp.scavio.dev/mcp",
      "headers": {
        "x-api-key": "YOUR_SCAVIO_API_KEY"
      }
    }
  }
}
```

### Zed

Add to settings (`Cmd+,`):

```json
{
  "assistant": {
    "mcp_servers": {
      "scavio": {
        "type": "http",
        "url": "https://mcp.scavio.dev/mcp",
        "headers": {
          "x-api-key": "YOUR_SCAVIO_API_KEY"
        }
      }
    }
  }
}
```

### Any MCP-Compatible Client

```json
{
  "type": "http",
  "url": "https://mcp.scavio.dev/mcp",
  "headers": {
    "x-api-key": "YOUR_SCAVIO_API_KEY"
  }
}
```

---

## Choosing which tools load

Scavio exposes 191 tools. Loading all of them costs 136KB of `tools/list` —
roughly 35k tokens of context in every session before the user has said anything,
and more tools than some clients will accept at all. So the server registers a
curated subset by default and lets you pick the rest. The sizes below are
measured, not estimated: `npm run toolslist` reproduces them.

`SCAVIO_PLATFORMS` is a comma-separated allowlist of platform keys:

| Value | Registers |
|-------|-----------|
| *(unset)* or `default` | Everything 0.12.x had, plus `extract` — **106 tools, 63KB** |
| `all` | every platform — **191 tools, 136KB** |
| `extract,sec,g2` | just those platforms — 11 tools, 10KB |
| `default,zillow,metaads` | the default set plus two more — 112 tools, 70KB |
| `none` | no platform tools, only `get_usage` |

Keys are matched case- and punctuation-insensitively, so `meta-ads`, `metaads`
and `META_ADS` are the same thing, and `twitter` resolves to `x`. An unknown key
is logged to stderr and skipped rather than failing the server.

`get_usage` always registers — it is free, and it is what every install guide
tells you to call to check the server works.

**Platform keys:** `extract`, `google`, `youtube`, `tiktok`, `instagram`,
`reddit`, `x`, `linkedin`, `threads`, `kuaishou`, `amazon`, `walmart`, `ebay`,
`target`, `homedepot`, `tiktok-shop`, `booking`, `airbnb`, `tripadvisor`,
`yelp`, `zillow`, `redfin`, `indeed`, `glassdoor`, `appstore`, `googleplay`,
`g2`, `capterra`, `googleads`, `metaads`, `sec`, `companieshouse`

### Local (stdio)

```json
{
  "mcpServers": {
    "scavio": {
      "command": "npx",
      "args": ["-y", "@scavio/mcp-server"],
      "env": {
        "SCAVIO_API_KEY": "YOUR_SCAVIO_API_KEY",
        "SCAVIO_PLATFORMS": "extract,google,zillow,redfin"
      }
    }
  }
}
```

### Remote (HTTP)

The hosted server has no env var to read, so pass the allowlist per connection —
either as a header or as a query parameter:

```json
{
  "scavio": {
    "type": "http",
    "url": "https://mcp.scavio.dev/mcp",
    "headers": {
      "x-api-key": "YOUR_SCAVIO_API_KEY",
      "x-scavio-platforms": "extract,google,sec,companieshouse"
    }
  }
}
```

```
https://mcp.scavio.dev/mcp?platforms=all
```

### Upgrading from 0.12.x

Nothing to do. The default set is exactly the 10 platforms 0.12.x registered,
plus Extract — every tool you were using still loads, and the context cost is
unchanged. Walmart grew from 2 tools to 7, so the count moves 100 → 106.

The 22 platforms added in 0.13.0 are opt-in. Add them additively:

```
SCAVIO_PLATFORMS=default,zillow,redfin,sec
```

One breaking fix worth knowing: `search_walmart` previously sent
`fulfillment_speed: "anytime"` on every call, which the API rejects. The
parameter is now `today` or `tomorrow` with no default.

---

## Available Tools

Every tool costs 1 credit per call unless its section says otherwise. Several
platforms price per endpoint (YouTube, Instagram, LinkedIn, Kuaishou) or per
request body (Extract, Threads, Walmart); `get_amazon_options` and `get_usage`
are free.

### [Extract](https://scavio.dev/docs/extract)

| Tool | Description |
|------|-------------|
| `extract_url` | Read any web page and return it as clean Markdown, plain text, or raw HTML |

Extract is tier-priced by the `mode` parameter, not flat: `normal` (plain fetch)
and `advanced` (full JavaScript rendering) cost 1 credit, `ultra` (residential
proxy, for hard bot walls) costs 2. Start at `normal` and escalate only when the
content comes back empty or blocked. You are billed only on a successful
extraction — a dead link, a bot wall or a timeout costs nothing. There is no
pagination: the whole page comes back in one call.

### [Google Search API](https://scavio.dev/docs/search-api)

| Tool | Description |
|------|-------------|
| `search_google` | Web search (v2) with organic results, ads, and AI Overview |
| `google_ai_mode` | AI Mode conversational answer with cited sources |
| `google_maps_search` | Search Google Maps for local businesses |
| `google_maps_place` | Place details: address, phone, hours, rating |
| `google_maps_reviews` | Reviews for a place with pagination |
| `google_shopping` | Product listings with price, store, and rating |
| `google_shopping_product` | Product detail and sellers |
| `google_shopping_stores` | More sellers for a product (pagination) |
| `google_flights` | Flight itineraries with prices and stops |
| `google_hotels` | Hotel search with prices and ratings |
| `google_hotels_detail` | Hotel property details |
| `google_news` | News results by query, topic, story, or publication |
| `google_trends` | Interest-over-time and related queries |
| `google_trend