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
1 toolweb_searchB
Perform a web search using a privacy-respecting SearXNG metasearch instance.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query to submit to SearXNG | |
| categories | No | Optional list of categories to search in (e.g. general, news, science, files, images, videos, music, it, social_media) | |
| engines | No | Optional list of specific search engines to use | |
| language | No | Language code for search results (e.g. en-US) | en-US |
| pageno | No | Page number of results to fetch |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of disclosing behavioral traits. It only mentions 'privacy-respecting' but omits details like rate limits, authentication needs, result pagination, or caching behavior. The output schema exists but is not referenced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential purpose without extraneous words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, the schema covers all parameters, and an output schema exists, the description is largely complete. However, it could briefly mention pagination or result limits associated with the pageno parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all 5 parameters described in the schema. The description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('perform a web search') and the specific resource ('privacy-respecting SearXNG metasearch instance'), making the tool's purpose unambiguous. With no sibling tools provided, differentiation is not required.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives, nor does it specify when not to use it. The mention of 'privacy-respecting' hints at a use case but does not explicitly state conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
With only one tool, there is no possibility of confusion between tools. The purpose is clearly singular.
The single tool name 'web_search' follows a clear verb_noun pattern, which is consistent and readable.
A single tool for a metasearch server feels thin but is acceptable for a focused purpose. However, it borders on being too minimal for the domain's potential scope.
The server covers the primary search operation but lacks related tools such as listing available engines or configuring search parameters, leaving moderate gaps.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Web search, news, page retrieval, sitemaps, and trending topics through Search1API.
Search the web, images, videos, news, and local businesses with robust filters, freshness controls…
Provides AI assistants with access to Seltz's powerful Web Search capabilities.
x402-gated web search gateway. Tools: search, search_enriched.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides privacy-focused web search capabilities through SearXNG metasearch engine, enabling web, image, video, and news searches without tracking. Includes comprehensive research tools that aggregate and analyze results from multiple search engines.34MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to perform privacy-respecting web searches through SearXNG, with support for multiple search engines, categories, and advanced filtering options.25
- 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
- FlicenseAqualityDmaintenanceEnables 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.1
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Knuckles-Team/searxng-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server