使用说明

网页搜索MCP服务器

一个可投入生产的模型上下文协议（MCP）服务器，通过SearXNG提供网页搜索功能。该服务器设计用于与大型语言模型（LLM）代理无缝集成，支持HTTP/SSE传输，并采用针对LLM优化的响应格式。

特点/特性

多引擎搜索 - 聚合来自Brave、DuckDuckGo、Startpage等的结果
针对大型语言模型（LLM）优化的 - 三款专为客服人员设计的工具，提供格式化回复
知识提取 - 从Wikidata中自动提取结构化事实
实时流媒体 - 通过HTTP/SSE实现MCP与实时客服集成
Docker 准备就绪 - 使用docker-compose实现完全容器化
生产特点 - 健康检查、指标监控、结构化日志记录、请求追踪

建筑学

┌─────────────────────┐
│   LLM Agent         │
│  (MCP Client)       │
└──────────┬──────────┘
           │ MCP over HTTP/SSE
           ↓
┌─────────────────────┐
│  Web Search MCP     │  Port 8003
│     Server          │
│  - 3 Search Tools   │
│  - REST API         │
│  - Metrics          │
└──────────┬──────────┘
           │ HTTP
           ↓
┌─────────────────────┐
│     SearXNG         │  Port 8888
│  (Meta-Search)      │
│  - Brave            │
│  - DuckDuckGo       │
│  - Startpage        │
│  - Wikipedia        │
└─────────────────────┘

快速入门

先决条件

Docker 和 Docker Compose
（可选）Python 3.11+ 用于本地开发

1. 克隆并启动

git clone https://github.com/slinusc/web-search-mcp-server.git
cd web-search-mcp-server
docker compose up -d

这开始了：

SearXNG 在8888端口（搜索后端）
MCP 服务器 在8003端口上（代理接口）

2. 测试API

# Quick search (LLM-optimized)
curl -X POST http://localhost:8003/api/quick_search \
  -H "Content-Type: application/json" \
  -d '{"query": "latest developments in AI"}'

# Structured search (with facts)
curl -X POST http://localhost:8003/api/structured_search \
  -H "Content-Type: application/json" \
  -d '{"query": "climate change 2024"}'

# Health check
curl http://localhost:8003/healthz

3. 连接您的MCP客户端

{
  "mcpServers": {
    "websearch": {
      "url": "http://localhost:8003/sse"
    }
  }
}

MCP 工具

1. `web_search`

全面搜索，包含完整元数据

{
  "query": "machine learning frameworks",
  "categories": "general",  # or "news", "images", "videos"
  "pageno": 1
}

返回：包含所有引擎、建议和信息框的完整SearXNG响应。

2. `quick_search`

快速，针对大型语言模型（LLM）优化的结果

{
  "query": "who invented the internet",
  "categories": "general"
}

返回结果：包含知识库的前10名排名结果，以及相关性评分和来源标注。

3. `structured_search`

以事实为中心，结合背景

{
  "query": "Python programming language",
  "categories": "general"
}

返回结果：排名结果 + Wikidata 属性 + 上下文片段 + 建议。

响应格式

快速搜索示例

{
  "ok": true,
  "request_id": "a1b2c3d4e5f6",
  "query": "Python programming",
  "total_results": 28,
  "knowledge_base": {
    "entity": "Python (programming language)",
    "description": "Python is a high-level, interpreted programming language...",
    "attributes": {
      "Developer": "Python Software Foundation",
      "First appeared": "1991",
      "Influenced by": "ABC, Modula-3, C"
    },
    "image": "https://upload.wikimedia.org/..."
  },
  "top_results": [
    {
      "rank": 1,
      "title": "Python.org",
      "url": "https://www.python.org/",
      "snippet": "Python is a programming language that lets you work quickly...",
      "score": 9.0,
      "engines": ["brave", "duckduckgo", "startpage"]
    }
  ],
  "engines_used": ["brave", "duckduckgo", "startpage", "wikipedia"]
}

REST API 参考

端点	方法	描述
`/sse`	GET	MCP SSE 流（用于代理）
`/messages`	POST	MCP客户端消息
`/api/search`	POST	通用网页搜索
`/api/quick_search`	POST	快速LLM优化搜索
`/api/structured_search`	POST	结构化事实搜索
`/healthz`	GET	健康检查
`/metrics`	GET	性能指标
`/tools`	GET	列出可用的MCP工具

配置

环境变量

# docker-compose.yml or .env
SEARXNG_URL=http://searxng:8080  # SearXNG backend URL
SEARXNG_TIMEOUT=10.0              # Request timeout (seconds)

SearXNG 配置

编辑 config/settings.yml 收件人：

启用/禁用搜索引擎
配置结果格式
设置速率限制
自定义搜索行为

关键设置：

search:
  formats:
    - html
    - json  # Required for MCP server

server:
  limiter: false  # Adjust for production

发展

本地设置

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -r requirements.txt

# Run server
python server.py

服务器运行于 http://localhost:8003

测试

# Test quick search
curl -X POST http://localhost:8003/api/quick_search \
  -H "Content-Type: application/json" \
  -d '{"query": "test query"}'

# Check metrics
curl http://localhost:8003/metrics

# List available tools
curl http://localhost:8003/tools | jq

Docker

构建

docker build -t mcp-server-websearch .

独立运行

docker run -d \
  --name mcp-websearch \
  -p 8003:8003 \
  -e SEARXNG_URL=http://searxng:8080 \
  mcp-server-websearch

编写（推荐）

# Start all services
docker compose up -d

# View logs
docker compose logs -f mcp-websearch

# Stop services
docker compose down

监测

健康检查

curl http://localhost:8003/healthz
# Response: ok

指标

curl http://localhost:8003/metrics

回答：

{
  "ok": true,
  "metrics": {
    "api_search_calls": 42,
    "api_quick_search_calls": 156,
    "api_structured_search_calls": 23,
    "mcp_call_tool_calls": 221,
    "searxng_requests": 221,
    "errors_total": 2
  }
}

代理集成

通用MCP客户端

服务器提供了三种MCP工具，这些工具对任何MCP兼容代理都是自动可用的：

web_search - 用于全面搜索，获取详细信息
quick_search - 为了快速获得顶级结果
structured_search - 用于处理结构化事实的研究

LangChain 集成

from langchain.tools import Tool

# Wrap the MCP tools
tools = [
    Tool(
        name="web_search",
        func=call_mcp_tool,  # Your MCP client wrapper
        description="Search the web for current information"
    )
]

用例

问题回答 - 快速回答并注明来源
研究助理 - 基于结构化事实的深入研究
RAG系统 - 获取当前信息以了解上下文
新闻监控 - 跟踪近期事件和动态
事实核查 - 从多个来源验证信息

安全注意事项

速率限制配置SearXNG limiter.toml 用于生产
API密钥不需要（SearXNG 是自托管的）
**CORS（跨源资源共享）**目前允许所有来源 - 生产环境中需限制
网络使用 Docker 网络来隔离服务

故障排除

SearXNG 返回 403 禁止访问

# Check if JSON format is enabled in config/settings.yml
docker exec searxng grep -A 3 "formats:" /etc/searxng/settings.yml

# Should show:
# formats:
#   - html
#   - json

连接被拒绝错误

# Ensure services are running
docker compose ps

# Check logs
docker compose logs searxng
docker compose logs mcp-websearch

没有搜索结果

# Test SearXNG directly
curl -X POST http://localhost:8888/search \
  -H "X-Forwarded-For: 127.0.0.1" \
  --data "q=test&format=json"

许可证

MIT 许可证 - 详见许可证文件中有详细信息。

致谢

SearXNG（注：这通常是一个搜索引擎的名称，直接翻译可能无具体含义，故保留原样） - 尊重隐私的元搜索引擎
模型上下文协议 - 人类中心主义的MCP规范
Starlette - 轻量级的ASGI框架

做出贡献

欢迎投稿！请：

为仓库创建分支（或“克隆仓库”）
创建一个特性分支
提交您的更改
推送到分支
提交一个拉取请求

支持

问题： GitHub 问题（或议题）
讨论： GitHub 讨论区