AI导哈

搜索服务MCP服务器

一个开源的模型上下文协议（MCP）服务器，连接到SearXNG实例并为大型语言模型（LLM）客户端提供网络搜索能力。

  • by torturado
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 torturado/searxng-mcp-server

使用说明

SearXNG MCP服务器

一个开源的模型上下文协议（MCP）服务器，连接到SearXNG实例，并向LLM客户端公开web搜索功能。

该项目提供了两个MCP工具：

  • search：通过SearXNG运行网络搜索，并返回结构化+可读的输出
  • fetch：加载URL并提取可读的页面内容

支持的传输：

  • stdio 适用于本地客户端（Cursor、Claude Desktop、本地代理运行时）
  • 远程客户端的流式HTTP（ChatGPT和Claude远程连接器）

为什么是这个项目？

大多数MCP搜索服务器依赖于第三方提供商或固定集成。 此项目是为运行自己的SearXNG实例并希望：

  • 在他们自己的控制下进行隐私友好的网络搜索
  • 一个本地和远程工作的MCP服务器
  • 易于扩展的小型、可理解的TypeScript代码

快速开始

npm install
cp .env.example .env
# edit .env and set SEARXNG_BASE_URL
npm run build
npm start

对于HTTP模式：

npm run start:http

技术栈

  • 语言： TypeScript
  • 运行时间： Node.js >=18
  • MCP-SDK： @modelcontextprotocol/sdk (^1.27.1)
  • HTTP服务器： 快递(^5.2.1)
  • 验证： 佐德(^4.3.6)
  • 环境加载器： Dotenv(^17.3.1)
  • 开发者： tsx
  • 构建： tsc （TypeScript编译器）

项目架构

flowchart LR
  Client[MCP Client]
  Stdio[Stdio Transport]
  Http[Streamable HTTP Transport]
  Core[MCP Server Core]
  SearchTool[search Tool]
  FetchTool[fetch Tool]
  SearxClient[SearXNG Client]
  ContentFetcher[Content Fetcher]
  Searx[SearXNG Instance]
  Web[Web Pages]

  Client --> Stdio --> Core
  Client --> Http --> Core
  Core --> SearchTool --> SearxClient --> Searx
  Core --> FetchTool --> ContentFetcher --> Web

关键架构决策：

  • 单服务器工厂： createSearxMcpServer() 定义工具一次。
  • 双交通入口： src/index.ts （stdio）和 src/http.ts （HTTP）。
  • 有状态HTTP会话： mcp-session-id 映射到可重用传输/会话状态。
  • 安全中间件： 主机/来源检查+可选的承载令牌身份验证。

入门指南

先决条件

  • Node.js 18+
  • 启用JSON响应格式的可访问SearXNG实例(format=json)

安装

npm install

配置

复制 .env.example 到 .env 并且至少设置：

SEARXNG_BASE_URL=https://your-searxng.instance

dotenv 是自动加载的，因此 npm start 读取 .env 没有额外的外壳出口。

构建

npm run build

跑

启动stdio服务器：

npm start

启动HTTP服务器：

npm run start:http

健康检查：

curl http://127.0.0.1:3100/health

项目结构

src/
  config.ts           # env parsing and validation
  searx-client.ts     # SearXNG API calls + response normalization
  content-fetcher.ts  # URL loading + readable text extraction
  server.ts           # MCP tool registration (search, fetch)
  index.ts            # stdio entrypoint
  http.ts             # Streamable HTTP entrypoint

其他文件：

  • .env.example -运行时配置的安全模板
  • .gitignore -排除机密并构建工件
  • LICENSE -MIT许可证文本

主要特点

  • MCP工具： search
    • 输入控件： query, pageno, language, categories, safesearch, timeRange, limit
    • 输出包括可读文本和结构化数据
  • MCP工具： fetch
    • 检索URL内容
    • 去除HTML噪声并按字节预算安全截断
  • 流式HTTP支持：
    • POST /mcp
    • GET /mcp
    • DELETE /mcp
    • GET /health
  • HTTP安全默认值：
    • 默认情况下绑定localhost
    • 可选的宿主和来源同种异体
    • 可选的承载身份验证（公开非本地绑定时需要）

环境变量

变量 必填 描述
SEARXNG_BASE_URL 是 您的SearXNG实例的基本URL。
SEARXNG_HEADERS 没有 带有SearXNG请求附加标头的JSON对象。
SEARXNG_TIMEOUT_MS 否 搜索超时（毫秒）。默认值： 15000.
FETCH_TIMEOUT_MS 否 URL获取超时（毫秒）。默认值： 10000.
FETCH_MAX_BYTES 否 返回的最大响应字节数 fetch默认值： 500000.
HTTP_PORT 否 可流式传输HTTP端口。默认值： 3100.
HTTP_BIND 否 绑定地址。默认本地： 127.0.0.1.
HTTP_ALLOWED_ORIGINS 否 允许的JSON数组 Origin 标题。
HTTP_ALLOWED_HOSTS 否 允许的JSON数组 Host 价值观。
HTTP_AUTH_TOKEN 有条件 需要时 HTTP_BIND 不是本地的。

使用 .env.example 作为规范模板。

开发工作流程

当前工作流程：

  1. 实施/调整逻辑 src/
  2. 构建于 npm run build
  3. 烟雾测试：
    • npm start 对于stdio
    • npm run start:http 并检查 /health
  4. 使用真实的MCP调用验证行为(search 和 fetch)

建议的协作工作流程：

  • 使用特征分支
  • 打开拉取请求以供审查
  • 标记发布里程碑的版本

编码标准

此代码库使用的约定：

  • 启用了严格的TypeScript
  • 不可信输入的显式运行时验证(zod)
  • 责任明确的小模块
  • 无效环境配置的快速故障行为
  • 清除错误消息和确定性默认值
  • 跟踪文件中没有秘密或个人价值

测试

自动化测试尚未包括在内。

当前验证方法：

  • 编译时检查： npm run build
  • 两种传输的运行时烟雾检查
  • 手动功能检查 search 和 fetch

建议下一步：

  • 为以下内容添加单元测试：
    • loadConfig 在 src/config.ts
    • 请求/响应处理 src/searx-client.ts
    • 提取和截断 src/content-fetcher.ts
    • 会话/安全行为 src/http.ts

贡献

欢迎捐款。

请遵守这些规则：

  • 用英语保存代码和文档
  • 不要承诺 .env 文件或秘密
  • 保持示例通用（没有个人域、用户名或令牌）
  • 跑 npm run build 在打开PR之前
  • 保持更改范围和记录

安全与隐私

  • .env 被git忽略，必须保持本地。
  • 仅在以下位置存储真实令牌、实例URL和私有标头 .env.
  • 在提交的文档和示例中使用占位符。

许可证

该项目根据 MIT许可证.

相关 MCP