SearchAPI.site - MCP 服务器

该项目提供了一个模型上下文协议 (MCP) 服务器，通过 SearchAPI.site 将 AI 助手连接到外部数据源（如 Google、Bing 等）。

• Glama
• Github
• NPM

<a href="https://glama.ai/mcp/servers/@mrgoonie/searchapi-mcp-server"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@mrgoonie/searchapi-mcp-server/badge" alt="SearchAPI Server MCP 服务器" /> </a>

可用平台

• Google - 网页搜索
• Google - 图片搜索
• Google - YouTube 搜索
• Google - 地图搜索
• Bing - 网页搜索
• Bing - 图片搜索
• Reddit
• X/Twitter
• Facebook 搜索
• Facebook 群组搜索
• Instagram
• TikTok

SearchAPI.site

• 网站
• API 文档
• Swagger UI 配置
• 在此创建 Search API 密钥 这里
• GitHub

支持的传输方式

• "stdio" 传输 - CLI 使用的默认传输
• "Streamable HTTP" 传输 - 用于基于 Web 的客户端
  • 实现认证 (Authorization 头部使用 Bearer <token>)
• "sse" 传输 (已弃用)
• 编写测试

如何使用

CLI

bash

通过 CLI 进行 Google 搜索

npm run dev:cli -- search-google --query "your search query" --api-key "your-api-key"

通过 CLI 进行 Google 图片搜索

npm run dev:cli -- search-google-images --query "your search query" --api-key "your-api-key"

通过 CLI 进行 YouTube 搜索

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

MCP 设置

对于本地配置使用 stdio 传输： json { "mcpServers": { "searchapi": { "command": "node", "args": ["/path/to/searchapi-mcp-server/dist/index.js"], "transportType": "stdio" } } }

对于远程 HTTP 配置： json { "mcpServers": { "searchapi": { "type": "http", "url": "http://mcp.searchapi.site/mcp" } } }

HTTP 传输的环境变量：

您可以使用以下环境变量来配置 HTTP 服务器：

• MCP_HTTP_HOST: 绑定的主机 (默认: 127.0.0.1)
• MCP_HTTP_PORT: 监听的端口 (默认: 8080)
• MCP_HTTP_PATH: 端点路径 (默认: /mcp)

---

源代码概述

什么是 MCP？

模型上下文协议 (MCP) 是一个开放标准，允许 AI 系统安全且有上下文地连接到外部工具和数据源。

该样板实现了 MCP 规范，并具有清晰的分层架构，可以扩展以构建针对任何 API 或数据源的自定义 MCP 服务器。

为什么使用这个样板？

• 生产就绪架构：遵循已发布的 MCP 服务器中使用的相同模式，CLI、工具、控制器和服务之间有明确的分离。
• 类型安全：使用 TypeScript 构建，以提高开发体验、代码质量和可维护性。
• 工作示例：包含一个完全实现的 IP 查找工具，展示了从 CLI 到 API 集成的完整模式。
• 测试框架：附带单元测试和 CLI 集成测试的基础设施，包括覆盖率报告。
• 开发工具：预配置了 ESLint、Prettier、TypeScript 和其他质量工具，适用于 MCP 服务器开发。

---

开始使用

前提条件- Node.js (>=18.x): Download

• Git: 用于版本控制

---

第一步：克隆并安装

bash

克隆仓库

git clone https://github.com/mrgoonie/searchapi-mcp-server.git cd searchapi-mcp-server

安装依赖

npm install

---

第二步：运行开发服务器

使用 stdio 传输（默认）在开发模式下启动服务器：

bash npm run dev:server

或者使用可流式 HTTP 传输：

bash npm run dev:server:http

这将启动 MCP 服务器，并启用热重载和 MCP 检查器，地址为 http://localhost:5173。

⚙️ 代理服务器监听端口 6277 🔍 MCP 检查器正在运行于 http://127.0.0.1:6274

当使用 HTTP 传输时，默认情况下服务器将在 http://127.0.0.1:8080/mcp 上可用。

---

第三步：测试示例工具

从命令行运行示例 IP 查找工具：

bash

在开发模式下使用 CLI

npm run dev:cli -- search-google --query "your search query" --api-key "your-api-key"

或者指定特定的 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"

---

架构

此样板遵循一种清晰的分层架构模式，该模式分离了关注点并促进了可维护性。

项目结构

src/ ├── cli/ # 命令行接口 ├── controllers/ # 业务逻辑 ├── resources/ # MCP 资源：向 LLMs 暴露来自服务器的数据和内容 ├── services/ # 外部 API 交互 ├── tools/ # MCP 工具定义 ├── types/ # 类型定义 ├── utils/ # 共享实用程序 └── index.ts # 入口点

层次与职责

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

• 目的：定义解析参数并调用控制器的命令行接口
• 命名：文件应命名为 <feature>.cli.ts
• 测试：CLI 集成测试位于 <feature>.cli.test.ts

工具层 (src/tools/*.tool.ts)

• 目的：定义带有模式和描述的 MCP 工具，供 AI 助手使用
• 命名：文件应命名为 <feature>.tool.ts，类型文件为 <feature>.types.ts
• 模式：每个工具应使用 zod 进行参数验证

控制器层 (src/controllers/*.controller.ts)

• 目的：实现业务逻辑、处理错误并格式化响应
• 命名：文件应命名为 <feature>.controller.ts
• 模式：应返回标准化的 ControllerResponse 对象

服务层 (src/services/*.service.ts)

• 目的：与外部 API 或数据源进行交互
• 命名：文件应命名为 <feature>.service.ts
• 模式：纯 API 交互，逻辑最少

实用程序层 (src/utils/*.util.ts)

• 目的：提供应用程序中的共享功能
• 关键实用程序：
  • logger.util.ts：结构化日志记录
  • error.util.ts：错误处理和标准化
  • formatter.util.ts：Markdown 格式化辅助函数

---

开发指南

开发脚本

bash

在开发模式下启动服务器（热重载 & 检查器）

npm run dev:server

在开发模式下运行 CLI

npm run dev:cli -- [command] [args]

构建项目

npm run build

在生产模式下启动服务器

npm run start:server

在生产模式下运行 CLI

npm run start:cli -- [command] [args]

测试

bash

运行所有测试

npm test

运行特定测试

npm test -- src/path/to/test.ts

生成测试覆盖率报告

npm run test:coverage

评估

evals 包加载一个 mcp 客户端，然后运行 index.ts 文件，因此在测试之间不需要重建。您可以通过在 npx 命令前加上环境变量来加载它们。完整的文档可以在这里找到这里。

bash OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/tools/searchapi.tool.ts## 代码质量

bash

代码检查

npm run lint

使用 Prettier 格式化代码

npm run format

检查类型

npm run typecheck

---

构建自定义工具

按照以下步骤向服务器添加自己的工具：

1. 定义服务层

在 src/services/ 中创建一个新的服务以与外部 API 交互：

typescript // 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('获取数据', { param }); // 在此处编写 API 交互代码 return { result: '示例数据' }; }

2. 创建控制器

在 src/controllers/ 中添加一个控制器来处理业务逻辑：

typescript // src/controllers/example.controller.ts import { Logger } from '../utils/log…