# mcp-server-searchapi

An MCP server for [SearchApi](https://www.searchapi.io) — Google web, news, scholar, and YouTube search as clean, agent-ready MCP tools.

[![npm version](https://img.shields.io/npm/v/mcp-server-searchapi.svg)](https://www.npmjs.com/package/mcp-server-searchapi)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

---

## Features

- **4 search tools** — web, news, Google Scholar, and YouTube.
- **Normalized output** — slimmed, consistent JSON tuned for LLM consumption (no raw SearchApi noise).
- **Bearer auth** — single `SEARCHAPI_API_KEY` env var; no extra config.
- **Retry / backoff** — automatic retry on 429 and 5xx with exponential backoff.
- **stdio transport** — plugs directly into any MCP-compatible host.
- **Zero-config run** — `npx mcp-server-searchapi` with no installation step.

---

## Tools

| Tool | Searches | Key params |
|------|----------|------------|
| `web_search` | Google organic results | `query` (required), `gl`, `hl`, `location`, `page` |
| `news_search` | Google News | `query` (required), `time_period` (`last_day` \| `last_week` \| `last_month` \| `last_year`), `gl`, `hl` |
| `scholar_search` | Google Scholar | `query` (required), `page`, `year_from` |
| `youtube_search` | YouTube | `query` (required), `gl`, `hl` |

---

## Requirements

- **Node.js ≥ 18**
- A [SearchApi](https://www.searchapi.io) API key (free tier available)

---

## Install & run

```bash
SEARCHAPI_API_KEY=your_key npx mcp-server-searchapi
```

No installation required. `npx` downloads and runs the server on the fly.

---

## Use with Claude Desktop / Claude Code

Add the following block to your MCP configuration file (`claude_desktop_config.json` for Claude Desktop, or `.claude/settings.json` for Claude Code):

```json
{
  "mcpServers": {
    "searchapi": {
      "command": "npx",
      "args": ["-y", "mcp-server-searchapi"],
      "env": { "SEARCHAPI_API_KEY": "your_key_here" }
    }
  }
}
```

Once configured, Claude can call `web_search`, `news_search`, `scholar_search`, and `youtube_search` directly.

---

## Example

Example `web_search` response (illustrative):

```json
{
  "results": [
    {
      "position": 1,
      "title": "Model Context Protocol",
      "link": "https://modelcontextprotocol.io",
      "source": "modelcontextprotocol.io",
      "snippet": "An open protocol that standardizes how applications provide context to large language models."
    }
  ],
  "related_searches": ["mcp server", "mcp tools"]
}
```

---

## Tool reference

### `web_search`

Search Google via SearchApi. Returns organic results plus optional answer box, knowledge graph summary, and related searches.

| Param | Type | Description |
|-------|------|-------------|
| `query` | string (required) | The search query. |
| `gl` | string | Country code, e.g. `"us"`, `"tw"` (default: `"us"`). |
| `hl` | string | Interface language, e.g. `"en"` (default: `"en"`). |
| `location` | string | Geographic location for the search. |
| `page` | integer | Results page number (default: 1). Google returns 10 results per page; use `page` to paginate — there is no `num` param. |

**Returns:** `{ results: [{position, title, link, source?, snippet?, date?}], answer?, knowledge?, related_searches? }`

---

### `news_search`

Search Google News via SearchApi. Returns recent articles with title, link, source, date, and snippet.

| Param | Type | Description |
|-------|------|-------------|
| `query` | string (required) | The news search query. |
| `time_period` | string | Restrict to a time window: `last_day`, `last_week`, `last_month`, or `last_year`. |
| `gl` | string | Country code, e.g. `"us"`. |
| `hl` | string | Interface language, e.g. `"en"`. |

**Returns:** `{ results: [{title, link, source?, date?, snippet?, thumbnail?}] }`

---

### `scholar_search`

Search Google Scholar via SearchApi. Returns academic results with title, link, authors, publication info, citation count, and snippet.

| Param | Type | Description |
|-------|------|-------------|
| `query` | string (required) | The scholarly search query. |
| `page` | integer | Results page number (default: 1). |
| `year_from` | integer | Only return results published from this year onward. |

**Returns:** `{ results: [{title, link, authors?, publication?, cited_by?, snippet?}] }`

---

### `youtube_search`

Search YouTube via SearchApi. Returns videos with title, link, channel, view count, publish time, and duration.

| Param | Type | Description |
|-------|------|-------------|
| `query` | string (required) | The YouTube search query. |
| `gl` | string | Country code, e.g. `"us"`. |
| `hl` | string | Interface language, e.g. `"en"`. |

**Returns:** `{ results: [{title, link, channel?, views?, published?, length?, description?}] }`

---

## Extending

The client in `src/searchapi-client.ts` is engine-agnostic — it accepts any engine name that SearchApi supports. Adding support for another engine (maps, flights, patents, shopping, and 20+ others) is a single new file: create `src/tools/<engine>.ts`, map the tool's input params to SearchApi query params, add a normalize helper in `src/normalize.ts`, and register the tool in `src/tools/index.ts`. No changes to the client or server wiring are required.

---

## Development

```bash
# Install dependencies
npm install

# Run unit tests (offline — no API key needed; fixtures are bundled)
npm test

# Build for distribution
npm run build
```

The unit tests run fully offline using fixture files in `test/fixtures/`. A separate live integration test (`test/live.test.ts`) exercises the real SearchApi endpoint — it runs automatically as part of `npm test` but is **skipped** unless `SEARCHAPI_API_KEY` is set:

```bash
SEARCHAPI_API_KEY=your_key npm test
```

---

## License

MIT — see [LICENSE](LICENSE).