Skip to main content
Glama
deenesjakoruzh
mrgoonie

SearchAPI MCP Server

by mrgoonie
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

SearchAPI.site - MCP Server

This project provides a Model Context Protocol (MCP) server that connects AI assistants to external data sources (Google, Bing, etc.) via SearchAPI.site.

Author: Claude

Available platforms

  • Google - Web Search

  • Google - Image Search

  • Google - YouTube Search

  • Google - Maps Search

  • Bing - Web Search

  • Bing - Image Search

  • Reddit

  • X/Twitter

  • Facebook Search

  • Facebook Group Search

  • Instagram

  • TikTok

SearchAPI.site

Related MCP server: WebSearch-MCP

Supported Transports

  • "stdio" transport - Default transport for CLI usage

  • "Streamable HTTP" transport - For web-based clients

    • Implement auth ("Authorization" headers with Bearer <token>)

  • "sse" transport (Deprecated)

  • Write tests

How to use

CLI

# Google search via CLI
npm run dev:cli -- search-google --query "your search query" --api-key "your-api-key"

# Google image search via CLI
npm run dev:cli -- search-google-images --query "your search query" --api-key "your-api-key"

# YouTube search via CLI
npm run dev:cli -- search-youtube --query "your search query" --api-key "your-api-key" --max-results 5

MCP Setup

For local configuration with stdio transport:

{
  "mcpServers": {
    "searchapi": {
      "command": "node",
      "args": ["/path/to/searchapi-mcp-server/dist/index.js"],
      "transportType": "stdio"
    }
  }
}

For remote HTTP configuration:

{
  "mcpServers": {
    "searchapi": {
      "type": "http",
      "url": "http://mcp.searchapi.site/mcp"
    }
  }
}

Environment Variables for HTTP Transport:

You can configure the HTTP server using these environment variables:

  • MCP_HTTP_HOST: The host to bind to (default: 127.0.0.1)

  • MCP_HTTP_PORT: The port to listen on (default: 8080)

  • MCP_HTTP_PATH: The endpoint path (default: /mcp)

Source Code Overview

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI systems to securely and contextually connect with external tools and data sources.

This boilerplate implements the MCP specification with a clean, layered architecture that can be extended to build custom MCP servers for any API or data source.

Why Use This Boilerplate?

  • Production-Ready Architecture: Follows the same pattern used in published MCP servers, with clear separation between CLI, tools, controllers, and services.

  • Type Safety: Built with TypeScript for improved developer experience, code quality, and maintainability.

  • Working Example: Includes a fully implemented IP lookup tool demonstrating the complete pattern from CLI to API integration.

  • Testing Framework: Comes with testing infrastructure for both unit and CLI integration tests, including coverage reporting.

  • Development Tooling: Includes ESLint, Prettier, TypeScript, and other quality tools preconfigured for MCP server development.

Getting Started

Prerequisites

  • Node.js (>=18.x): Download

  • Git: For version control

Step 1: Clone and Install

# Clone the repository
git clone https://github.com/mrgoonie/searchapi-mcp-server.git
cd searchapi-mcp-server

# Install dependencies
npm install

Step 2: Run Development Server

Start the server in development mode with stdio transport (default):

npm run dev:server

Or with the Streamable HTTP transport:

npm run dev:server:http

This starts the MCP server with hot-reloading and enables the MCP Inspector at http://localhost:5173.

⚙️ Proxy server listening on port 6277 🔍 MCP Inspector is up and running at http://127.0.0.1:6274

When using HTTP transport, the server will be available at http://127.0.0.1:8080/mcp by default.

Step 3: Test the Example Tool

Run the example IP lookup tool from the CLI:

# Using CLI in development mode
npm run dev:cli -- search-google --query "your search query" --api-key "your-api-key"

# Or with a specific IP
npm run dev:cli -- search-google --query "your search query" --api-key "your-api-key" --limit 10 --offset 0 --sort "date:d" --from_date "2023-01-01" --to_date "2023-12-31"

Architecture

This boilerplate follows a clean, layered architecture pattern that separates concerns and promotes maintainability.

Project Structure

src/
├── cli/              # Command-line interfaces
├── controllers/      # Business logic
├── resources/        # MCP resources: expose data and content from your servers to LLMs
├── services/         # External API interactions
├── tools/            # MCP tool definitions
├── types/            # Type definitions
├── utils/            # Shared utilities
└── index.ts          # Entry point

Layers and Responsibilities

CLI Layer (src/cli/*.cli.ts)

  • Purpose: Define command-line interfaces that parse arguments and call controllers

  • Naming: Files should be named <feature>.cli.ts

  • Testing: CLI integration tests in <feature>.cli.test.ts

Tools Layer (src/tools/*.tool.ts)

  • Purpose: Define MCP tools with schemas and descriptions for AI assistants

  • Naming: Files should be named <feature>.tool.ts with types in <feature>.types.ts

  • Pattern: Each tool should use zod for argument validation

Controllers Layer (src/controllers/*.controller.ts)

  • Purpose: Implement business logic, handle errors, and format responses

  • Naming: Files should be named <feature>.controller.ts

  • Pattern: Should return standardized ControllerResponse objects

Services Layer (src/services/*.service.ts)

  • Purpose: Interact with external APIs or data sources

  • Naming: Files should be named <feature>.service.ts

  • Pattern: Pure API interactions with minimal logic

Utils Layer (src/utils/*.util.ts)

  • Purpose: Provide shared functionality across the application

  • Key Utils:

    • logger.util.ts: Structured logging

    • error.util.ts: Error handling and standardization

    • formatter.util.ts: Markdown formatting helpers

Development Guide

Development Scripts

# Start server in development mode (hot-reload & inspector)
npm run dev:server

# Run CLI in development mode
npm run dev:cli -- [command] [args]

# Build the project
npm run build

# Start server in production mode
npm run start:server

# Run CLI in production mode
npm run start:cli -- [command] [args]

Testing

# Run all tests
npm test

# Run specific tests
npm test -- src/path/to/test.ts

# Generate test coverage report
npm run test:coverage

evals

The evals package loads an mcp client that then runs the index.ts file, so there is no need to rebuild between tests. You can load environment variables by prefixing the npx command. Full documentation can be found here.

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/tools/searchapi.tool.ts

Code Quality

# Lint code
npm run lint

# Format code with Prettier
npm run format

# Check types
npm run typecheck

Building Custom Tools

Follow these steps to add your own tools to the server:

1. Define Service Layer

Create a new service in src/services/ to interact with your external API:

// src/services/example.service.ts
import { Logger } from '../utils/logger.util.js';

const logger = Logger.forContext('services/example.service.ts');

export async function getData(param: string): Promise<any> {
	logger.debug('Getting data', { param });
	// API interaction code here
	return { result: 'example data' };
}

2. Create Controller

Add a controller in src/controllers/ to handle business logic:

// src/controllers/example.controller.ts
import { Logger } from '../utils/logger.util.js';
import * as exampleService from '../services/example.service.js';
import { formatMarkdown } from '../utils/formatter.util.js';
import { handleControllerError } from '../utils/error-handler.util.js';
import { ControllerResponse } from '../types/common.types.js';

const logger = Logger.forContext('controllers/example.controller.ts');

export interface GetDataOptions {
	param?: string;
}

export async function getData(
	options: GetDataOptions = {},
): Promise<ControllerResponse> {
	try {
		logger.debug('Getting data with options', options);

		const data = await exampleService.getData(options.param || 'default');

		const content = formatMarkdown(data);

		return { content };
	} catch (error) {
		throw handleControllerError(error, {
			entityType: 'ExampleData',
			operation: 'getData',
			source: 'controllers/example.controller.ts',
		});
	}
}

3. Implement MCP Tool

Create a tool definition in src/tools/:

// src/tools/example.tool.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
import { Logger } from '../utils/logger.util.js';
import { formatErrorForMcpTool } from '../utils/error.util.js';
import * as exampleController from '../controllers/example.controller.js';

const logger = Logger.forContext('tools/example.tool.ts');

const GetDataArgs = z.object({
	param: z.string().optional().describe('Optional parameter'),
});

type GetDataArgsType = z.infer<typeof GetDataArgs>;

async function handleGetData(args: GetDataArgsType) {
	try {
		logger.debug('Tool get_data called', args);

		const result = await exampleController.getData({
			param: args.param,
		});

		return {
			content: [{ type: 'text' as const, text: result.content }],
		};
	} catch (error) {
		logger.error('Tool get_data failed', error);
		return formatErrorForMcpTool(error);
	}
}

export function register(server: McpServer) {
	server.tool(
		'get_data',
		`Gets data from the example API, optionally using \`param\`.
Use this to fetch example data. Returns formatted data as Markdown.`,
		GetDataArgs.shape,
		handleGetData,
	);
}

4. Add CLI Support

Create a CLI command in src/cli/:

// src/cli/example.cli.ts
import { program } from 'commander';
import { Logger } from '../utils/logger.util.js';
import * as exampleController from '../controllers/example.controller.js';
import { handleCliError } from '../utils/error-handler.util.js';

const logger = Logger.forContext('cli/example.cli.ts');

program
	.command('get-data')
	.description('Get example data')
	.option('--param <value>', 'Optional parameter')
	.action(async (options) => {
		try {
			logger.debug('CLI get-data called', options);

			const result = await exampleController.getData({
				param: options.param,
			});

			console.log(result.content);
		} catch (error) {
			handleCliError(error);
		}
	});

5. Register Components

Update the entry points to register your new components:

// In src/cli/index.ts
import '../cli/example.cli.js';

// In src/index.ts (for the tool)
import exampleTool from './tools/example.tool.js';
// Then in registerTools function:
exampleTool.register(server);

Debugging Tools

MCP Inspector

Access the visual MCP Inspector to test your tools and view request/response details:

  1. Run npm run dev:server

  2. Open http://localhost:5173 in your browser

  3. Test your tools and view logs directly in the UI

Server Logs

Enable debug logs for development:

# Set environment variable
DEBUG=true npm run dev:server

# Or configure in ~/.mcp/configs.json

Publishing Your MCP Server

When ready to publish your custom MCP server:

  1. Update package.json with your details

  2. Update README.md with your tool documentation

  3. Build the project: npm run build

  4. Test the production build: npm run start:server

  5. Publish to npm: npm publish

License

ISC License

{
	"searchapi": {
		"environments": {
			"DEBUG": "true",
			"SEARCHAPI_API_KEY": "value"
		}
	}
}

Note: For backward compatibility, the server will also recognize configurations under the full package name (searchapi-mcp-server) or the unscoped package name (searchapi-mcp-server) if the searchapi key is not found. However, using the short searchapi key is recommended for new configurations.

Co-Authors

  • Claude Code (Claude AI Assistant)

  • Goon

Available Tools

3 tools
search_googleC

Performs a Google search using SearchAPI.site. Requires a search "query" string, can be able to search multiple keywords that separated by commas. Returns formatted search results including titles, snippets, and links.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesThe search query to perform
limitNoMaximum number of results to return (1-100)
offsetNoOffset for pagination
sortNoSort order (e.g., "date:d" for newest first)
from_dateNoStart date for filtering results (format: YYYY-MM-DD)
to_dateNoEnd date for filtering results (format: YYYY-MM-DD)

TDQS

C2.8/5.0
Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool 'Returns formatted search results including titles, snippets, and links,' which gives some output context, but lacks critical behavioral details like rate limits, authentication requirements, error handling, pagination behavior (beyond the offset parameter), or whether this is a read-only operation. The mention of 'SearchAPI.site' hints at a third-party service but doesn't explain implications.

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

Conciseness3/5

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

The description is reasonably concise with three sentences, but it's not optimally front-loaded. The first sentence states the purpose, but the second sentence awkwardly mixes parameter guidance ('Requires a search "query" string') with feature description ('can be able to search multiple keywords'). The third sentence covers return values. Some redundancy exists (e.g., 'query' is mentioned twice), and the structure could be tighter for better clarity.

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

Completeness2/5

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

Given no annotations, no output schema, and 6 parameters (though well-documented in schema), the description is incomplete. It lacks behavioral context (e.g., rate limits, auth), doesn't explain the relationship with sibling tools, and provides minimal guidance on usage. For a search tool with multiple parameters and no structured output definition, more contextual information would be helpful for an AI agent to use it effectively.

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 all 6 parameters thoroughly. The description adds minimal value beyond the schema: it mentions the query parameter and that it 'can be able to search multiple keywords that separated by commas' (though awkwardly phrased), but doesn't explain other parameters like limit, offset, sort, from_date, or to_date. Baseline 3 is appropriate when schema does the heavy lifting.

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?

The description clearly states the tool 'Performs a Google search using SearchAPI.site' with a specific verb ('Performs') and resource ('Google search'), distinguishing it from sibling tools like search_google_images and search_youtube by focusing on general web search. However, it doesn't explicitly contrast with siblings beyond the different search types.

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 provides no guidance on when to use this tool versus alternatives like search_google_images or search_youtube. It mentions the tool can search multiple keywords separated by commas, but this is more about parameter usage than contextual guidance. No explicit when/when-not instructions or alternative recommendations are included.

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

search_google_imagesB

Performs a Google image search using SearchAPI.site. Requires a search query and your SearchAPI.site API key. Returns formatted image search results including titles, thumbnails, and source links.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesThe image search query to perform
limitNoMaximum number of results to return (1-100)
offsetNoOffset for pagination
sortNoSort order (e.g., "date:d" for newest first)
from_dateNoStart date for filtering results (format: YYYY-MM-DD)
to_dateNoEnd date for filtering results (format: YYYY-MM-DD)

TDQS

B3.2/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the API key requirement (authentication need) and describes the return format ('formatted image search results including titles, thumbnails, and source links'), which adds value beyond the input schema. However, it doesn't mention rate limits, error conditions, or other behavioral traits like whether results are cached or real-time.

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

Conciseness4/5

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

The description is appropriately sized with three concise sentences that each add value: what it does, what it requires, and what it returns. It's front-loaded with the core purpose. There's minimal waste, though it could be slightly more structured with bullet points for the three key pieces of information.

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

Completeness3/5

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

For a tool with 6 parameters, 100% schema coverage, but no annotations and no output schema, the description provides adequate but incomplete context. It covers the purpose, authentication requirement, and return format, but doesn't address error handling, rate limits, or provide examples. The absence of an output schema means the description's mention of return format is helpful but could be more detailed.

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 all 6 parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema - it mentions 'search query' and 'API key' but doesn't explain parameter interactions, defaults, or usage examples. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

The description clearly states the tool 'performs a Google image search using SearchAPI.site' which is a specific verb+resource combination. It distinguishes itself from sibling tools like 'search_google' and 'search_youtube' by specifying it's for images, though it doesn't explicitly contrast with them in the description text itself.

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 mentions the requirement for a SearchAPI.site API key, which provides some usage context. However, it offers no guidance on when to use this tool versus the sibling tools (search_google, search_youtube) or any alternatives. There's no explicit 'when' or 'when not' guidance.

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

search_youtubeB

Performs a YouTube search using SearchAPI.site. Requires a search query and your SearchAPI.site API key. Returns formatted YouTube search results including video titles, thumbnails, descriptions, and links. Supports optional parameters for pagination, sorting, filtering by date and duration.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesThe YouTube search query to perform
maxResultsNoMaximum number of results to return (1-50)
pageTokenNoToken for pagination to get next/previous page of results
orderNoSort order for results
publishedAfterNoNumber of days to filter videos from
videoDurationNoFilter by video duration

TDQS

B3.4/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the API key requirement (auth needs) and describes the return format (video titles, thumbnails, descriptions, links), which adds value beyond the input schema. However, it doesn't cover rate limits, error handling, or other operational constraints.

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

Conciseness4/5

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

The description is appropriately sized with four sentences that each add value: purpose, requirements, returns, and optional features. It's front-loaded with core functionality. Minor improvement could come from tighter phrasing, but there's no wasted content.

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

Completeness3/5

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

For a search tool with 6 parameters, 100% schema coverage, and no output schema, the description provides adequate context on what the tool does and returns. However, without annotations or output schema, it lacks details on response structure, error cases, or performance characteristics that would help an agent use it effectively.

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 all 6 parameters thoroughly. The description adds minimal value by listing optional parameters (pagination, sorting, filtering by date and duration) but doesn't provide additional syntax, format, or usage details beyond what's in the schema. This meets the baseline for high schema coverage.

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 clearly states the specific action ('Performs a YouTube search') and resource ('using SearchAPI.site'), distinguishing it from sibling tools like search_google and search_google_images by specifying YouTube as the search target. It provides a complete verb+resource+scope combination.

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 mentions when to use this tool (for YouTube searches) but provides no guidance on when to choose it versus the sibling tools search_google or search_google_images. There's no explicit comparison or exclusion criteria, leaving the agent to infer usage context.

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. Dates show when Glama detected each change.

  1. 3 tool updates
    • First observedsearch_google
    • First observedsearch_google_images
    • First observedsearch_youtube
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose targeting a specific search type: Google web search, Google image search, and YouTube search. The descriptions explicitly differentiate them by platform and result format, with no overlap in functionality that could cause confusion.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with 'search_' prefix followed by the target platform (google, google_images, youtube). This predictable naming scheme makes it easy for agents to understand and select the appropriate tool.

Tool Count4/5

Three tools is reasonable for a search API server, covering major search platforms. However, it feels slightly thin—adding tools for other platforms (like news or shopping search) could make it more comprehensive, but the current count is appropriate for the core functionality.

Completeness4/5

The toolset covers the essential search operations for Google web, images, and YouTube, which aligns well with the server's purpose. A minor gap is the lack of a general search tool that could handle other platforms or unified search, but agents can work effectively with the provided tools.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • MCP Server

    GobinFan
    F
    license
    B
    quality
    D
    maintenance
    Implements the Model Context Protocol (MCP) to provide AI models with a standardized interface for connecting to external data sources and tools like file systems, databases, or APIs.
    1
    153
    -

  • WebSearch-MCP

    mnhlt
    A
    license
    B
    quality
    C
    maintenance
    A Model Context Protocol server that enables AI assistants to perform real-time web searches, retrieving up-to-date information from the internet via a Crawler API.
    1
    62
    40
    ISC

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mrgoonie/searchapi-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server