# SearchAPI MCP服务器 ## 基本信息 - Slug: `mrgoonie-searchapi-mcp-server` - Source: modelscope - Publisher: @mrgoonie/searchapi-mcp-server - Categories: search / rag-systems / browser-automation - Hosted: No - License: MIT License - Source URL: https://www.modelscope.cn/mcp/servers/@mrgoonie/searchapi-mcp-server ## 简介 通过SearchAPI.site将AI助手连接到外部数据源（如Google、Bing等），并通过模型上下文协议（MCP）实现对网络信息的安全和上下文访问。 ## MCP Server 详情 # SearchAPI.site - MCP 服务器 该项目提供了一个模型上下文协议 (MCP) 服务器，通过 [SearchAPI.site](https://searchapi.site) 将 AI 助手连接到外部数据源（如 Google、Bing 等）。 - [Glama](https://glama.ai/mcp/servers/@mrgoonie/searchapi-mcp-server) - [Github](https://github.com/mrgoonie/searchapi-mcp-server) - [NPM](https://www.npmjs.com/package/searchapi-mcp-server) SearchAPI Server MCP 服务器 ### 可用平台 - [x] Google - 网页搜索 - [x] Google - 图片搜索 - [x] Google - YouTube 搜索 - [ ] Google - 地图搜索 - [x] Bing - 网页搜索 - [ ] Bing - 图片搜索 - [ ] Reddit - [ ] X/Twitter - [ ] Facebook 搜索 - [ ] Facebook 群组搜索 - [ ] Instagram - [ ] TikTok ## SearchAPI.site - [网站](https://searchapi.site) - [API 文档](https://searchapi.site/api-docs) - [Swagger UI 配置](https://searchapi.site/api-docs/swagger-ui-init.js) - 在此创建 Search API 密钥 [这里](https://searchapi.site/profile) - [GitHub](https://github.com/mrgoonie/searchapi) ## 支持的传输方式 - [x] ["stdio"](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#stdio) 传输 - CLI 使用的默认传输 - [x] ["Streamable HTTP"](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) 传输 - 用于基于 Web 的客户端 - [ ] 实现认证 (`Authorization` 头部使用 `Bearer `) - [ ] ~~"sse" 传输~~ **[(已弃用)](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#backwards-compatibility)** - [ ] 编写测试 ## 如何使用 ### 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](https://nodejs.org/) - **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`) - **目的**：定义解析参数并调用控制器的命令行接口 - **命名**：文件应命名为 `.cli.ts` - **测试**：CLI 集成测试位于 `.cli.test.ts` ### 工具层 (`src/tools/*.tool.ts`) - **目的**：定义带有模式和描述的 MCP 工具，供 AI 助手使用 - **命名**：文件应命名为 `.tool.ts`，类型文件为 `.types.ts` - **模式**：每个工具应使用 zod 进行参数验证 ### 控制器层 (`src/controllers/*.controller.ts`) - **目的**：实现业务逻辑、处理错误并格式化响应 - **命名**：文件应命名为 `.controller.ts` - **模式**：应返回标准化的 `ControllerResponse` 对象 ### 服务层 (`src/services/*.service.ts`) - **目的**：与外部 API 或数据源进行交互 - **命名**：文件应命名为 `.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 命令前加上环境变量来加载它们。完整的文档可以在这里找到[这里](https://www.mcpevals.io/docs)。 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 { logger.debug('获取数据', { param }); // 在此处编写 API 交互代码 return { result: '示例数据' }; } ## 2. 创建控制器 在 `src/controllers/` 中添加一个控制器来处理业务逻辑： typescript // src/controllers/example.controller.ts import { Logger } from '../utils/log…