SearXNG MCP Server
Searxng Mcp
CLI 或 API | MCP | Agent
版本:2.1.0
文档 — 有关 MCP 工具、Python API 和控制台脚本的安装、部署、用法,以及配置 SearXNG 实例的指南,均维护在官方文档中。
Related MCP server: SearXNG MCP Server
概述
Searxng Mcp 是一个生产级 Agent 和模型上下文协议(MCP)服务器,旨在直接与 SearXNG 搜索引擎 MCP 服务器对接,为 Agentic AI 提供支持!
主要特性
整合式动作路由 MCP 工具: 通过将方法分组为经过优化的可切换工具模块,最大限度地减少 token 开销,并消除 LLM 上下文中的工具冗余。
企业级安全: 全面支持 Eunomia 策略、OIDC token 委派以及细粒度的执行上下文跟踪。
集成图代理: 内置 Pydantic AI 代理,支持 Agent 控制协议(ACP)和标准 Web 界面(AG-UI)。
原生遥测与追踪: 开箱即用的 OpenTelemetry 导出和原生 Langfuse 追踪。
CLI 或 API
该代理封装了 SearXNG 搜索引擎 MCP 服务器(面向 Agentic AI!)的 API。您可以通过编程方式或通过其集成的执行入口点与之交互。
有关如何使用底层 API 包装器、扩展 schema 绑定和开发者 SDK 参考的详细说明,请参阅 docs/index.md。
MCP
该服务器利用动态动作路由工具来优化 token 开销并最大化 IDE 兼容性。
可用的 MCP 工具
下表由 MCP 服务器自动生成 — 请勿手动编辑。
精简版动作路由工具(MCP_TOOL_MODE=condensed)
MCP 工具 | 切换环境变量 | 描述 |
|
| 运行 SearXNG 搜索并将其结果原生摄取到 epistemic-graph 中。 |
|
| 启动交互式 SearXNG 搜索 UI 应用:查询框、分类筛选器和可点击的结果列表,由现有的 web_search 工具通过宿主中介的 MCP Apps 桥接提供支持。当人类需要直观地查看并与搜索结果交互而不是阅读原始 JSON 时,请使用此工具。它不会驱动浏览器或渲染任意网页——仅执行此搜索工作流。 |
|
| 读取/编辑嵌入式 SearXNG 实例的 settings.yml |
| — | 使用尊重隐私的 SearXNG 元搜索实例执行网络搜索。 |
4 个动作路由工具 · 0 个详细 1:1 工具。除非其 <DOMAIN>TOOL 切换设置为 false,否则每个工具均处于启用状态;MCP_TOOL_MODE 选择工具面(**intent 默认* — 六个动词工具,按需加载的细粒度集合 · condensed 动作路由 · verbose 1:1 · both)。自动生成 — 请勿编辑。*
详细的工具 schema、参数形状和验证约束保存在 docs/usage.md 中。
动态工具选择与可见性
此 MCP 服务器支持在运行时进行动态工具集选择和可见性过滤。这使您可以限制公开工具的范围,以防止撑爆 LLM 的上下文窗口。
您可以通过多种输入渠道配置工具过滤:
CLI 参数: 在启动时传递
--tools或--toolsets(或其禁用对应项--disabled-tools和--disabled-toolsets)。环境变量: 定义标准环境变量:
MCP_ENABLED_TOOLS/MCP_DISABLED_TOOLSMCP_ENABLED_TAGS/MCP_DISABLED_TAGS
HTTP SSE 请求头: 在传输初始化期间传递自定义请求头:
x-mcp-enabled-tools/x-mcp-disabled-toolsx-mcp-enabled-tags/x-mcp-disabled-tags
HTTP SSE 请求查询参数: 直接将查询参数附加到您的传输连接 URL:
?tools=tool1,tool2?tags=tag1
当提供查询字符串或参数时,一个无 LLM 的知识图谱解析层(使用 DynamicToolOrchestrator)会将查询意图与已知的工具标签、名称或描述进行匹配,并具备安全回退和自动化的 24 小时后台缓存刷新功能。
MCP 配置示例
安装面向连接器的
[mcp]附加组件。 示例使用searxng-mcp[mcp]通过agent-utilities[mcp]添加 FastMCP / FastAPI;所需的 Agent Utilities 核心仍携带epistemic-graph[full]。[agent-runtime]附加组件还额外启用了模型编排。
stdio 传输(本地 IDE — Cursor、Claude Desktop、VS Code)
{
"mcpServers": {
"searxng-mcp": {
"command": "uvx",
"args": [
"--from",
"searxng-mcp[mcp]",
"searxng-mcp"
],
"env": {
"MCP_TOOL_MODE": "intent",
"SEARCH_APPTOOL": "true",
"SEARXNG_EMBEDDED": "true",
"SEARXNG_KG_INGEST": "true",
"USE_RANDOM_INSTANCE": "false"
}
}
}
}运行时引用需要支持别名的启动器,例如 GraphOS。其他启动器必须省略这些条目,并通过自己的运行时密钥边界注入解析后的值。
Streamable-HTTP 传输(网络化 / 生产环境)
{
"mcpServers": {
"searxng-mcp": {
"command": "uvx",
"args": [
"--from",
"searxng-mcp[mcp]",
"searxng-mcp",
"--transport",
"streamable-http",
"--port",
"8000"
],
"env": {
"TRANSPORT": "streamable-http",
"HOST": "127.0.0.1",
"PORT": "8000",
"MCP_TOOL_MODE": "intent",
"SEARCH_APPTOOL": "true",
"SEARXNG_EMBEDDED": "true",
"SEARXNG_KG_INGEST": "true",
"USE_RANDOM_INSTANCE": "false"
}
}
}
}或者,通过 url 连接到预先部署的 Streamable-HTTP 实例:
{
"mcpServers": {
"searxng-mcp": {
"url": "http://localhost:8000/searxng-mcp/mcp"
}
}
}以最小权限 stdio 子进程运行经过审查的容器镜像(无监听器或已发布端口):
docker run -i --rm \
--read-only \
--cap-drop=ALL \
--security-opt=no-new-privileges \
--pids-limit=256 \
--tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
-e TRANSPORT=stdio \
-e MCP_TOOL_MODE=intent \
-e SEARCH_APPTOOL=true \
-e SEARXNG_EMBEDDED=true \
-e SEARXNG_KG_INGEST=true \
-e USE_RANDOM_INSTANCE=false \
registry.example.invalid/searxng-mcp@sha256:<digest> searxng-mcp对于容器化网络 HTTP,请通过运营商拥有的部署配置文件提供经过身份验证的 TLS 入口(或直接服务器 TLS)、精确的 MCP_ALLOWED_HOSTS 以及精确的受信任代理 CIDR 策略。生成器不会发出未经身份验证的非回环监听器。
根据代码读取的环境表面(MCP_TOOL_MODE + 包变量)自动生成 — 请勿编辑。
其他部署选项
searxng-mcp 可以作为本地 stdio 进程或容器运行,也可以位于远程网络边界之后。部署指南 提供了详细的传输契约。
本地容器 — 以最小权限 stdio 子进程启动经过审查的不可变镜像,无监听器或已发布端口。
远程 URL — 通过运营商提供的经过身份验证的 HTTPS 入口连接。将其 URL、出站身份引用、信任配置文件和精确的
MCP_ALLOWED_HOSTS保存在AgentConfig中。
Agent
此仓库包含一个完全集成的 Pydantic AI 图代理。它通过 Agent 控制协议(ACP) 进行通信,并与 Agent Web UI(AG-UI) 和终端界面无缝交互。
运行 Agent CLI
要启动交互式命令行代理:
# Set credentials
export SEARXNG_URL="your_value"
# Run the agent server
searxng-agent --provider openai --model-id gpt-4oDocker Compose 编排
以下 docker/agent.compose.yml 将 Agent、Web UI 和终端界面配置在一起:
version: '3.8'
services:
searxng-mcp-mcp:
image: example/searxng-mcp@sha256:<digest>
container_name: searxng-mcp-mcp
hostname: searxng-mcp-mcp
restart: always
env_file:
- ../.env
environment:
- PYTHONUNBUFFERED=1
- HOST=0.0.0.0
- PORT=8000
- TRANSPORT=streamable-http
ports:
- "8000:8000"
healthcheck:
test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
searxng-mcp-agent:
image: example/searxng-mcp@sha256:<digest>
container_name: searxng-mcp-agent
hostname: searxng-mcp-agent
restart: always
depends_on:
- searxng-mcp-mcp
env_file:
- ../.env
command: [ "searxng-agent" ]
environment:
- PYTHONUNBUFFERED=1
- HOST=0.0.0.0
- PORT=9001
- MCP_URL=http://searxng-mcp-mcp:8000/mcp
- PROVIDER=${PROVIDER:-openai}
- MODEL_ID=${MODEL_ID:-gpt-4o}
- ENABLE_WEB_UI=True
- ENABLE_OTEL=True
ports:
- "9001:9001"
healthcheck:
test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9001/health')"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
有关图节点架构的详细说明、自定义技能配置和代理追踪指南,请参阅 docs/deployment.md。
安全与治理
直接构建于企业级 agent-utilities 核心之上,完全支持标准安全参数:
访问控制与策略执行
Eunomia 策略: 细粒度的、策略驱动的工具授权。支持
none、本地embedded(mcp_policies.json)或集中式remote模式。OIDC Token 委派: 符合 RFC 8693 token 交换规范,用于将经过身份验证的用户凭据从 Web UI / ACP → Agent → MCP 流转。
作用域凭据: 执行上下文运行限制为特定的调用者身份。
运行时安全网格
特性 | 功能 | 启用方式 |
工具防护 | 敏感度检查,带有人工在环验证 | 默认启用 |
提示注入防御 | 输入扫描、重复监控和递归循环阻止 | 默认启用 |
上下文安全防护 | 卡死循环检测器和上下文溢出预警 | 默认启用 |
环境变量
包环境变量
变量 | 示例 | 描述 |
|
| |
|
| |
|
| 选项:stdio、streamable-http、sse |
|
| 禁用 searxng_search_app MCP 应用(ui:// 搜索界面) |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| 选项:none、embedded、remote |
|
| |
|
| |
| — | 两者都留空则使用捆绑/嵌入的 SearXNG 实例(默认 — 见下方 SEARXNG_EMBEDDED)。设置其中一个以指向外部实例(例如集群自己的 http://searxng.arpa)——显式 URL 始终优先于嵌入实例。 |
| — | |
| — | |
| secret-injected | |
|
| |
|
| |
|
| 零配置自包含搜索:当 SEARXNG_URL/SEARXNG_INSTANCE_URL 未设置时,生成并使用此 MCP 服务器拥有的私有、仅回环的 SearXNG 实例(需要 |
| — | 嵌入实例的用户可编辑 settings.yml 覆盖文件位于:$XDG_CONFIG_HOME/searxng-mcp/settings.yml。默认为 ~/.config。 |
继承的 agent-utilities 变量(适用于每个连接器)
变量 | 示例 | 描述 |
|
| 工具表面: |
| — | 逗号分隔的工具允许列表 |
| — | 逗号分隔的工具拒绝列表 |
| — | 逗号分隔的标签允许列表 |
| — | 逗号分隔的标签拒绝列表 |
| — | 出站 MCP 子认证: |
| — | OIDC 客户端 ID(服务账户认证) |
|
| OIDC 服务账户的运行时密钥引用 |
| — | HTTP Basic 用户名( |
|
| HTTP Basic 认证的运行时密钥引用( |
|
| 详细日志 |
|
| 无缓冲 stdout(推荐在容器中使用) |
|
| 代理连接的 MCP 服务器 URL |
|
| 代理的 LLM 提供商 |
|
| 代理的模型 ID |
|
| 提供 AG-UI Web 界面 |
20 个包变量 + 16 个继承变量。从 .env.example 和共享的 agent-utilities 集合自动生成 — 请勿编辑。
服务器读取的所有变量。参见 .env.example 作为复制粘贴的起点。
SearXNG 连接
变量 | 描述 | 默认值 |
| 要查询的 SearXNG 实例的基础 URL |
|
| 显式的实例 URL 覆盖 | — |
| SearXNG 实例的 Basic-auth 用户名(如受保护) | — |
| SearXNG 实例的 Basic-auth 密码(如受保护) | — |
| 随机选择一个公共 SearXNG 实例,而不是使用 |
|
| 将每个搜索结果原生摄取到已配置的完整知识图谱引擎中;失败会明确报错 |
|
| 零配置的自包含搜索:当未设置 |
|
MCP 服务器 / 传输
变量 | 描述 | 默认值 |
|
|
|
| 绑定主机(HTTP 传输) |
|
| 绑定端口(HTTP 传输) |
|
| 工具面: |
|
| 以逗号分隔的工具允许/拒绝列表 | — |
| 以逗号分隔的标签允许/拒绝列表 | — |
遥测与治理
变量 | 描述 | 默认值 |
| 启用 OpenTelemetry 导出 |
|
| OTLP 收集器端点 | — |
| OTLP 认证密钥 | — |
| OTLP 协议(例如 | — |
| 授权模式: |
|
| 嵌入式策略文件 |
|
| 远程 Eunomia 服务器 URL | — |
安装
选择与你要运行的内容相匹配的附加组件:
附加组件 | 安装内容 | 适用场景 |
| 面向连接器的 MCP 服务器( | 你只运行 MCP 服务器(最小的安装 / 镜像) |
| 代理运行时( | 你运行 集成代理 |
| 全部( | 开发 / 两种面都需要 |
# Connector-focused MCP server (includes the shared graph engine)
uv pip install "searxng-mcp[mcp]"
# Agent runtime (adds model orchestration to the shared graph engine)
uv pip install "searxng-mcp[agent]"
# Everything (development)
uv pip install "searxng-mcp[all]" # or: python -m pip install "searxng-mcp[all]"容器镜像(:mcp 与 :agent)
一个多阶段的 docker/Dockerfile 构建两个尺寸恰到好处的镜像,通过 --target 选择:
镜像标签 | 构建目标 | 内容 | 入口点 |
|
|
|
|
|
|
|
|
docker build --target mcp -t example/searxng-mcp:mcp docker/ # connector-focused MCP server
docker build --target agent -t example/searxng-mcp:agent-local docker/ # agent runtimedocker/mcp.compose.yml 运行面向连接器的 :mcp 服务器;docker/agent.compose.yml 运行代理(immutable agent digest)并附带一个同置的 :mcp 边车。
知识图谱数据库(epistemic-graph)
[mcp] 和 [agent] 都通过必需的 Agent Utilities 核心依赖(epistemic-graph[full])携带 epistemic-graph 引擎。[mcp] 附加组件保持服务器面向连接器;[agent] 额外启用模型编排。本地部署可以使用捆绑的引擎。对于生产环境或共享状态,请将 epistemic-graph 作为专用数据库服务运行,并配置运行时使用它。部署方案(单节点 + Raft 高可用)、连接配置和架构图记录在 epistemic-graph 部署指南 中。
文档
完整文档以官方文档站点的形式发布,是安装、部署和日常运维的推荐参考。
页面 | 内容 |
pip、源码、附加组件、预构建 Docker 镜像 | |
运行 MCP 与代理服务器、Compose、Caddy + Technitium、环境配置 | |
| |
使用 Docker 部署 SearXNG | |
生态系统角色与标准化包模式 | |
概念注册表( |
AGENTS.md 是贡献者/代理的规范指南。
仓库所有者
贡献
欢迎贡献!请在提交拉取请求前执行本地检查,以确保代码质量:
使用
ruff format .格式化代码使用
ruff check .进行 lint 检查使用
mypy .验证类型安全使用
pytest执行测试套件
使用 agent-utilities-deployment 部署
使用整合的 agent-utilities-deployment 工作流配置此包。它会在已安装包、可编辑源码或不可变容器路径之间进行选择;仅在 AgentConfig 中记录运行时密钥和 TLS 配置文件引用;并运行 doctor、注册、策略、可观测性和回滚门禁。请让你的代理执行 “使用 agent-utilities-deployment 部署 searxng-mcp”。
安装模式 | 命令 |
已安装包 |
|
可编辑源码 |
|
不可变容器 | 通过运维人员选择的编排器部署 |
该仓库不嵌入任何部署配置文件、凭据值、证书路径或环境特定端点。请在运行时通过 AgentConfig 和所配置的密钥提供程序提供这些内容。
受治理的能力契约
此包附带一个紧凑的规范技能面,专业流程以引用工作流的形式保留。当前的 MCP 工具、技能元数据、connector_manifest.yml、本体、映射、形状、夹具、迁移、工具模式指纹和认证元数据构成一份版本化的能力契约。请将它们一起验证;不要依赖过时的工具名称或历史遗留的按任务划分的技能包装器。
运行时端点、凭据、证书信任、租户身份、保留策略, 以及可观测性策略均属于部署输入,绝不是打包值。 在启用网络传输、连接器接入、GraphOS 委派或追踪导出之前,请参阅 配置、信任和隐私。
Available Tools
6 toolssearxng_get_settingsSearxng Get SettingsARead-onlyIdempotent
Read the EMBEDDED SearXNG instance's active settings.yml
(CONCEPT:SR-KG.compute.embedded-instance): the user override at
$XDG_CONFIG_HOME/searxng-mcp/settings.yml if one exists, else the
packaged default, plus its path. Informational only when an external
SEARXNG_URL is configured.
Inputs: no named parameters. Returns: object
searxng_ingest_searchSearxng Ingest SearchB
Run a SearXNG search and natively ingest its results into medulla.
Wire-First: performs the search, then pushes each result into the knowledge graph
as a search :Document (+ :SearchQuery / :SearchEngine typed nodes and their
:resultOf / :fromEngine links). Best-effort: ingested is None when no engine
is reachable. CONCEPT:AU-KG.ingest.enterprise-source-extractor.
Inputs: query (required), pageno, engines, language, +1 more. Returns: object
searxng_reset_settingsSearxng Reset SettingsADestructiveIdempotent
Delete the EMBEDDED SearXNG user override settings.yml, reverting to the packaged default on the next spawn.
Inputs: apply_now. Returns: object
searxng_search_appSearxng Search AppA
Launch an interactive SearXNG search-UI app: a query box, category filters, and a clickable results list, backed by the existing web_search tool through the host-mediated MCP Apps bridge. Use this when a human should see and interact with search results visually rather than read raw JSON. Does NOT drive a browser or render arbitrary web pages -- only this search workflow.
Inputs: query. Returns: object
searxng_set_settingsSearxng Set SettingsA
Deep-merge overrides_json into the EMBEDDED SearXNG user override
settings.yml (created on first use; the packaged default is never
modified), then stop the running embedded instance so the next search
respawns with the new settings (unless apply_now=false).
Inputs: merge, apply_now, overrides_json. Returns: object
web_searchWeb SearchBRead-onlyIdempotent
Perform a web search using a privacy-respecting SearXNG metasearch instance.
Inputs: query (required), pageno, engines, language, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
The three search-related tools are distinguishable by purpose: web_search returns raw results, searxng_ingest_search also writes into the knowledge graph, and searxng_search_app launches an interactive UI. The settings tools are clearly separated into get/set/reset with little overlap.
Most tools use a consistent searxng_ snake_case prefix and verb_noun style, but web_search breaks the prefix convention and uses a different verb-noun order. The set remains readable, but the naming pattern is not uniform.
Six tools is a reasonable, well-scoped surface for a SearXNG integration with search, ingestion, settings, and a UI entry point. No obvious tool feels redundant enough to warrant removal.
The surface covers search, search-result ingestion, embedded settings lifecycle, and a visual search app. Minor gaps exist, such as no explicit engine/category listing or status tool, but core workflows are present.
Maintenance
Related MCP Connectors
Search the web, images, videos, news, and local businesses with robust filters, freshness controls…
Multi-engine web and platform search, news, Google Maps places, page reading, sitemaps, and trends.
Google, Bing, DuckDuckGo and Google Maps search results, free without an API key.
Provides AI assistants with access to Seltz's powerful Web Search capabilities.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to perform privacy-respecting web searches through SearXNG, with support for multiple search engines, categories, and advanced filtering options.27ISC
- AlicenseAqualityDmaintenanceEnables web search, image search, and news search through a self-hosted SearXNG instance. Provides privacy-focused meta-search capabilities aggregating results from multiple search engines.31MIT
- AlicenseAqualityDmaintenanceEnables web search capabilities via a SearXNG instance, allowing for filtered searches across categories like news, images, and science. It supports multi-language queries, time-range filtering, and safe search options to provide formatted results with metadata.1MIT
- FlicenseAqualityDmaintenanceEnables privacy-respecting web, image, video, and news searches through SearxNG metasearch engine, with options for URL fetching and time filtering.575 PyPI-