Skip to main content
Glama
Ahmednsh

searchapi-mcp-server

by Ahmednsh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

searchapi-mcp-server

CI

npx @ahmednsh/searchapi-mcp-server

MCP server exposing 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, then add the server to claude_desktop_config.json (%AppData%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS):

{
  "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.

Related MCP server: Synthetic Web Search MCP 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

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

License

MIT

Available Tools

4 tools
google_jobsA

Search Google Jobs via SearchApi. Returns job listings with title, company, location, apply link, and a short description.

ParametersJSON Schema
NameRequiredDescriptionDefault
qYesJob search query (e.g. software engineer)
locationNoLocation to search in (e.g. "Riyadh, Saudi Arabia")

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full behavioral burden. It does disclose the return fields (title, company, location, apply link, description), which is genuinely useful, but says nothing about pagination, result limits, rate limits, or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the action front-loaded and the return contents summarized compactly. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter search tool with no output schema, the description adequately covers what is returned and the query surface. A brief note on result volume or pagination would close the remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both `q` and `location` are already documented with examples in the schema. The description adds no format or syntax detail beyond what the schema provides, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Search) and resource (Google Jobs), and names the provider (SearchApi), so the agent knows exactly what the tool does. It differentiates implicitly from google_shopping/youtube_search by the job-listings scope, but never names or contrasts a sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied by the name and the word 'Search Google Jobs' — an agent can infer it is for job queries. There is no explicit when-to-use, when-not-to-use, or routing guidance relative to google_search, which can also return job-adjacent web results.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

google_shoppingA

Search Google Shopping via SearchApi. Returns products with title, price, seller, rating, and delivery info.

ParametersJSON Schema
NameRequiredDescriptionDefault
qYesProduct search query
glNoTwo-letter country code for the market (e.g. us, sa)
include_linksNoInclude Google product links for each result (long tracking URLs; default false)

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It helpfully states that results include title, price, seller, rating, and delivery info, but it omits operational details such as pagination, result limits, authentication needs, or rate limits. This is adequate but incomplete for a search endpoint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The core purpose and return content are front-loaded, and the structure is easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple 3-parameter schema and the absence of an output schema, the description provides a useful return-field overview and clear purpose. It is nearly complete, though it could mention pagination or result-count behavior to fully support invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents q, gl, and include_links thoroughly. The description adds no parameter-specific meaning beyond what the schema provides, making the baseline score of 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Search Google Shopping via SearchApi.' This clearly distinguishes it from sibling tools like google_search, google_jobs, and youtube_search by naming the Shopping vertical. It also lists the returned product fields, making the tool's scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance, no exclusions, and does not mention alternatives such as google_search for general queries. It only implies usage through the phrase 'Search Google Shopping,' which is the bare minimum.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.2
    • First observedgoogle_jobs
    • First observedgoogle_search
    • First observedgoogle_shopping
    • First observedyoutube_search
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a clearly distinct search vertical: shopping, jobs, YouTube, and general web. There is no overlap in purpose or output type, so an agent can easily select the right tool for a given query.

Naming Consistency5/5

All names follow a consistent snake_case pattern of provider/vertical + search (google_shopping, google_jobs, youtube_search, google_search). The convention is predictable and readable across the set.

Tool Count5/5

Four tools is a well-scoped set for a search aggregator, with each tool representing a distinct search category and no redundancy. The count falls comfortably within the typical 3-15 range for a focused server.

Completeness3/5

The surface covers four popular verticals but lacks common search types such as news, images, maps, or scholarly results that a general SearchApi wrapper would typically offer. This gap may force agents to work around missing capabilities for many real-world tasks.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Synthetic Web Search MCP

    parnexcodes
    A
    license
    B
    quality
    D
    maintenance
    Exposes the Synthetic API as an MCP tool to enable web searching within Claude and other compatible applications. It provides formatted search results including titles, URLs, and text snippets for enhanced model context.
    1
    6 npm
    22
    MIT

  • Gemini Research MCP

    claudiusbotticus
    F
    license
    Not graded
    quality
    D
    maintenance
    Provides real-time web research and URL summarization capabilities using Gemini 2.5 Flash with native Google Search grounding. It enables users to perform factual searches and summarize web content directly within MCP-compatible clients like Claude Desktop.
    17
    -