# searchapi-mcp-server

[![CI](https://github.com/Ahmednsh/searchapi-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/Ahmednsh/searchapi-mcp-server/actions)

```bash
npx @ahmednsh/searchapi-mcp-server
```

MCP server exposing [SearchApi.io](https://www.searchapi.io/) as four tools: Google Search, Google Shopping, Google Jobs, and YouTube Search. Results come back as compact structured text built for an LLM context — direct answers first, no raw JSON.

> Community project — not affiliated with or endorsed by SearchApi.io.
> "SearchApi" is a trademark of its respective owner.

## Claude Desktop setup

Get an API key at [searchapi.io](https://www.searchapi.io/), then add the server to `claude_desktop_config.json` (`%AppData%\Claude\` on Windows, `~/Library/Application Support/Claude/` on macOS):

```json
{
  "mcpServers": {
    "searchapi": {
      "command": "npx",
      "args": ["-y", "@ahmednsh/searchapi-mcp-server"],
      "env": {
        "SEARCHAPI_API_KEY": "your-api-key"
      }
    }
  }
}
```

Restart Claude Desktop. The four tools appear under the "searchapi" server.

## Tools

### google_search

`q` (required), `num` (1–20, default 10), `gl` (country code, e.g. `sa`), `hl` (language code, e.g. `ar`).

Direct-answer features (answer box, knowledge graph, AI overview) are placed before the organic results whenever Google returns them:

```
Search results for "capital of Saudi Arabia":

---

[Answer box]
Saudi Arabia Capital: Riyadh

---

1. Riyadh
   https://en.wikipedia.org/wiki/Riyadh
   Riyadh is the capital and largest city of Saudi Arabia. It is also the capital of the Riyadh Province and the centre of the Riyadh Governorate.
2. Riyadh | Population, Climate, Map, History, & Facts
   https://www.britannica.com/place/Riyadh
   Riyadh is Saudi Arabia's capital and largest city. It became the capital of the Saud dynasty in 1824 and, except for a brief period in the ...
```

### google_shopping

`q` (required), `gl` (country code), `include_links` (boolean, default `false`).

```
Shopping results for "wireless mouse" (showing 10 of 40):

1. Logitech M220 Silent Wireless Mouse
   $13.83 — Walmart — 4.8★ (44,000 reviews)
   Free 90-day returns
2. Logitech G305 Lightspeed Wireless Gaming Mouse
   $29.99 — Target — 4.6★ (8,100 reviews)
   30-day returns
```

### google_jobs

`q` (required), `location` (e.g. `"Riyadh, Saudi Arabia"`).

```
Job results for "software engineer" in "Riyadh, Saudi Arabia":

1. Senior Software Engineer - Backend — Delivery Hero
   Riyadh Saudi Arabia · via Delivery Hero
   No degree mentioned
   Apply: https://careers.deliveryhero.com/job/senior-software-engineer-backend-in-riyadh-saudi-arabia-jid-7417
   About the opportunity We are looking for a highly talented Senior Backend Engineer to join our Riyadh office. If you are looking for a place where ...
```

### youtube_search

`q` (required).

```
YouTube results for "model context protocol tutorial":

1. Model Context Protocol Clearly Explained | MCP Beyond the Hype
   https://www.youtube.com/watch?v=tzrwxLNHtRY
   codebasics ✓ — 557,404 views — 15:04 — 1 year ago
   This video contains a very simple explanation of MCP, also known as Model Context Protocol. We will first understand what ...
2. What is MCP? Integrate AI Agents with Databases & APIs
   https://www.youtube.com/watch?v=eur8dUO9mvE
   IBM Technology ✓ — 684,035 views — 3:46 — 1 year ago
   Dive into the world of Model Context Protocol and learn how to seamlessly connect AI agents to databases, APIs, and more.
```

## For developers

- **Error semantics:** tool execution failures (missing/invalid key, HTTP 429/4xx/5xx, network errors) return a readable message with `isError: true`, so clients and models can distinguish a failed call from search content. "No results" is deliberately **not** an error — an empty search succeeded, and the message tells the model to change keywords instead of retrying.
- **`include_links`** on `google_shopping` is off by default because Google Shopping product links are ~500-character tracking URLs pointing back at Google, not at the merchant; the seller name is shown instead. Set `include_links: true` if you need them.
- **Output caps:** at most 10 results per call (the header says `showing 10 of N` when truncated); job descriptions are stripped of HTML and cut at 250 characters.
- **Layout:** `src/index.ts` registers the tools and talks to SearchApi; `src/format.ts` holds the pure response-to-text formatters, unit-tested in `src/format.test.ts` (`npm test`).

## Development

```bash
git clone https://github.com/Ahmednsh/searchapi-mcp-server.git && cd searchapi-mcp-server && npm install && npm run build
```

```bash
npm test
```

## License

MIT