Skip to main content
Glama
Knuckles-Team

SearXNG MCP Server

Searxng Mcp

CLI 或 API | MCP | Agent

PyPI - Version MCP Server PyPI - Downloads GitHub Repo stars GitHub forks GitHub contributors PyPI - License GitHub GitHub last commit (by committer) GitHub pull requests GitHub closed pull requests GitHub issues GitHub top language GitHub language count GitHub repo size GitHub repo file count (file type) PyPI - Wheel PyPI - Implementation

版本: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_ingest_search

KGTOOL

运行 SearXNG 搜索并将其结果原生摄取到 epistemic-graph 中。

searxng_search_app

SEARCH_APPTOOL

启动交互式 SearXNG 搜索 UI 应用:查询框、分类筛选器和可点击的结果列表,由现有的 web_search 工具通过宿主中介的 MCP Apps 桥接提供支持。当人类需要直观地查看并与搜索结果交互而不是阅读原始 JSON 时,请使用此工具。它不会驱动浏览器或渲染任意网页——仅执行此搜索工作流。

searxng_settings

CONFIGTOOL

读取/编辑嵌入式 SearXNG 实例的 settings.yml

web_search

使用尊重隐私的 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_TOOLS

    • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

  • HTTP SSE 请求头: 在传输初始化期间传递自定义请求头:

    • x-mcp-enabled-tools / x-mcp-disabled-tools

    • x-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-4o

Docker 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、本地 embeddedmcp_policies.json)或集中式 remote 模式。

  • OIDC Token 委派: 符合 RFC 8693 token 交换规范,用于将经过身份验证的用户凭据从 Web UI / ACP → Agent → MCP 流转。

  • 作用域凭据: 执行上下文运行限制为特定的调用者身份。

运行时安全网格

特性

功能

启用方式

工具防护

敏感度检查,带有人工在环验证

默认启用

提示注入防御

输入扫描、重复监控和递归循环阻止

默认启用

上下文安全防护

卡死循环检测器和上下文溢出预警

默认启用


环境变量

包环境变量

变量

示例

描述

HOST

0.0.0.0

PORT

8000

TRANSPORT

stdio

选项:stdio、streamable-http、sse

SEARCH_APPTOOL

true

禁用 searxng_search_app MCP 应用(ui:// 搜索界面)

ENABLE_OTEL

True

OTEL_EXPORTER_OTLP_ENDPOINT

http://localhost:8080/api/public/otel

OTEL_EXPORTER_OTLP_PUBLIC_KEY_REF

secret://telemetry/otlp-public-key

OTEL_EXPORTER_OTLP_SECRET_KEY_REF

secret://telemetry/otlp-secret-key

OTEL_EXPORTER_OTLP_PROTOCOL

http/protobuf

EUNOMIA_TYPE

none

选项:none、embedded、remote

EUNOMIA_POLICY_FILE

mcp_policies.json

EUNOMIA_REMOTE_URL

http://eunomia-server:8000

SEARXNG_INSTANCE_URL

两者都留空则使用捆绑/嵌入的 SearXNG 实例(默认 — 见下方 SEARXNG_EMBEDDED)。设置其中一个以指向外部实例(例如集群自己的 http://searxng.arpa)——显式 URL 始终优先于嵌入实例。

SEARXNG_URL

SEARXNG_USERNAME

SEARXNG_PASSWORD

secret-injected

USE_RANDOM_INSTANCE

false

SEARXNG_KG_INGEST

true

SEARXNG_EMBEDDED

true

零配置自包含搜索:当 SEARXNG_URL/SEARXNG_INSTANCE_URL 未设置时,生成并使用此 MCP 服务器拥有的私有、仅回环的 SearXNG 实例(需要 searxng-mcp[embedded] 扩展;没有它则静默无效)。

XDG_CONFIG_HOME

嵌入实例的用户可编辑 settings.yml 覆盖文件位于:$XDG_CONFIG_HOME/searxng-mcp/settings.yml。默认为 ~/.config。

继承的 agent-utilities 变量(适用于每个连接器)

变量

示例

描述

MCP_TOOL_MODE

intent

工具表面:intent | condensed | verbose | both

MCP_ENABLED_TOOLS

逗号分隔的工具允许列表

MCP_DISABLED_TOOLS

逗号分隔的工具拒绝列表

MCP_ENABLED_TAGS

逗号分隔的标签允许列表

MCP_DISABLED_TAGS

逗号分隔的标签拒绝列表

MCP_CLIENT_AUTH

出站 MCP 子认证:oidc-client-credentials | basic | none

OIDC_CLIENT_ID

OIDC 客户端 ID(服务账户认证)

OIDC_CLIENT_SECRET_REF

secret://identity/oidc-client-secret

OIDC 服务账户的运行时密钥引用

MCP_BASIC_AUTH_USERNAME

HTTP Basic 用户名(MCP_CLIENT_AUTH=basic

MCP_BASIC_AUTH_PASSWORD_REF

secret://identity/mcp-basic-password

HTTP Basic 认证的运行时密钥引用(MCP_CLIENT_AUTH=basic

DEBUG

False

详细日志

PYTHONUNBUFFERED

1

无缓冲 stdout(推荐在容器中使用)

MCP_URL

http://localhost:8000/mcp

代理连接的 MCP 服务器 URL

PROVIDER

openai

代理的 LLM 提供商

MODEL_ID

gpt-4o

代理的模型 ID

ENABLE_WEB_UI

True

提供 AG-UI Web 界面

20 个包变量 + 16 个继承变量。从 .env.example 和共享的 agent-utilities 集合自动生成 — 请勿编辑。

服务器读取的所有变量。参见 .env.example 作为复制粘贴的起点。

SearXNG 连接

变量

描述

默认值

SEARXNG_URL

要查询的 SearXNG 实例的基础 URL

http://localhost:8080

SEARXNG_INSTANCE_URL

显式的实例 URL 覆盖

SEARXNG_USERNAME

SearXNG 实例的 Basic-auth 用户名(如受保护)

SEARXNG_PASSWORD

SearXNG 实例的 Basic-auth 密码(如受保护)

USE_RANDOM_INSTANCE

随机选择一个公共 SearXNG 实例,而不是使用 SEARXNG_URL

false

SEARXNG_KG_INGEST

将每个搜索结果原生摄取到已配置的完整知识图谱引擎中;失败会明确报错

true

SEARXNG_EMBEDDED

零配置的自包含搜索:当未设置 SEARXNG_URL/SEARXNG_INSTANCE_URL 时,启动并使用本服务器自有的仅限回环的私有 SearXNG 实例(需要 pip install searxng-mcp[embedded];未安装该附加组件时静默空操作)

true

MCP 服务器 / 传输

变量

描述

默认值

TRANSPORT

stdiostreamable-httpsse

stdio

HOST

绑定主机(HTTP 传输)

0.0.0.0

PORT

绑定端口(HTTP 传输)

8000

MCP_TOOL_MODE

工具面:condensedverboseboth

condensed

MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

以逗号分隔的工具允许/拒绝列表

MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

以逗号分隔的标签允许/拒绝列表

遥测与治理

变量

描述

默认值

ENABLE_OTEL

启用 OpenTelemetry 导出

True

OTEL_EXPORTER_OTLP_ENDPOINT

OTLP 收集器端点

OTEL_EXPORTER_OTLP_PUBLIC_KEY / OTEL_EXPORTER_OTLP_SECRET_KEY

OTLP 认证密钥

OTEL_EXPORTER_OTLP_PROTOCOL

OTLP 协议(例如 http/protobuf

EUNOMIA_TYPE

授权模式:noneembeddedremote

none

EUNOMIA_POLICY_FILE

嵌入式策略文件

mcp_policies.json

EUNOMIA_REMOTE_URL

远程 Eunomia 服务器 URL


安装

选择与你要运行的内容相匹配的附加组件:

附加组件

安装内容

适用场景

searxng-mcp[mcp]

面向连接器的 MCP 服务器(agent-utilities[mcp] — FastMCP/FastAPI + epistemic-graph[full]

你只运行 MCP 服务器(最小的安装 / 镜像)

searxng-mcp[agent]

代理运行时(agent-utilities[agent-runtime,logfire] — 模型编排 + epistemic-graph[full]

你运行 集成代理

searxng-mcp[all]

全部(mcp + agent + logfire

开发 / 两种面都需要

# 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 选择:

镜像标签

构建目标

内容

入口点

example/searxng-mcp:mcp

--target mcp

searxng-mcp[mcp]面向连接器,包含 epistemic-graph[full];无模型编排栈

searxng-mcp

example/searxng-mcp@sha256:<digest>

--target agent(默认)

searxng-mcp[agent]代理运行时,模型编排 + epistemic-graph[full]

searxng-agent

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 runtime

docker/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、环境配置

使用

web_search 工具、Python API、控制台脚本

支撑平台

使用 Docker 部署 SearXNG

概述

生态系统角色与标准化包模式

概念

概念注册表(CONCEPT:SRX-*

AGENTS.md 是贡献者/代理的规范指南。


仓库所有者

GitHub 关注者 GitHub 用户的星标


贡献

欢迎贡献!请在提交拉取请求前执行本地检查,以确保代码质量:

  • 使用 ruff format . 格式化代码

  • 使用 ruff check . 进行 lint 检查

  • 使用 mypy . 验证类型安全

  • 使用 pytest 执行测试套件

使用 agent-utilities-deployment 部署

使用整合的 agent-utilities-deployment 工作流配置此包。它会在已安装包、可编辑源码或不可变容器路径之间进行选择;仅在 AgentConfig 中记录运行时密钥和 TLS 配置文件引用;并运行 doctor、注册、策略、可观测性和回滚门禁。请让你的代理执行 “使用 agent-utilities-deployment 部署 searxng-mcp

安装模式

命令

已安装包

uv tool install "searxng-mcp[mcp]",然后运行 searxng-mcp

可编辑源码

uv pip install -e ".[agent]",然后运行 searxng-mcp

不可变容器

通过运维人员选择的编排器部署 registry.example.invalid/searxng-mcp@sha256:<digest>

该仓库不嵌入任何部署配置文件、凭据值、证书路径或环境特定端点。请在运行时通过 AgentConfig 和所配置的密钥提供程序提供这些内容。

受治理的能力契约

此包附带一个紧凑的规范技能面,专业流程以引用工作流的形式保留。当前的 MCP 工具、技能元数据、connector_manifest.yml、本体、映射、形状、夹具、迁移、工具模式指纹和认证元数据构成一份版本化的能力契约。请将它们一起验证;不要依赖过时的工具名称或历史遗留的按任务划分的技能包装器。

运行时端点、凭据、证书信任、租户身份、保留策略, 以及可观测性策略均属于部署输入,绝不是打包值。 在启用网络传输、连接器接入、GraphOS 委派或追踪导出之前,请参阅 配置、信任和隐私

Available Tools

1 tool

TDQS

A3.6/5.0
Disambiguation5/5

With only one tool, there is no possibility of confusion between tools. The purpose is clearly singular.

Naming Consistency5/5

The single tool name 'web_search' follows a clear verb_noun pattern, which is consistent and readable.

Tool Count3/5

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.

Completeness3/5

The server covers the primary search operation but lacks related tools such as listing available engines or configuring search parameters, leaving moderate gaps.

Maintenance

ActivityActive
ResponsivenessSyncing

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

Related MCP Servers

  • A
    license
    A
    quality
    D
    maintenance
    Provides 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.
    3
    4
    MIT
  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to perform privacy-respecting web searches through SearXNG, with support for multiple search engines, categories, and advanced filtering options.
    25
  • A
    license
    A
    quality
    D
    maintenance
    Enables 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.
    3
    1
    MIT
  • F
    license
    A
    quality
    D
    maintenance
    Enables 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

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