Kindly Web Search MCP 服务器

关键词

网页搜索内容渲染浏览器自动化信息检索自动化工作流

使用说明（简明概览，非运行细则）

  • 项目简介

    • Kindly Web Search MCP 服务器是一个基于 MCP 协议的后端服务，提供两项核心工具：web_search（全网检索与结果的上下文渲染）与 get_content（对单个 URL 的内容获取与渲染）。
    • 通过多种传输方式（stdio、SSE、HTTP）对接客户端，并支持多种网页内容提取策略（专门解析 StackExchange、GitHub Issue/Discussions、Wikipedia、arXiv 等；其余情况回落到头LESS 的“无头浏览器”网页加载器）。
    • 提供对环境变量的统一管理、诊断输出、以及对浏览器自动化的完整封装与容错处理。

  • 主要功能点

    • MCP 服务实现：使用 FastMCP 提供 MCP 服务端能力，具备工具注册、会话上下文、消息处理等能力。
    • 工具集合：
      • web_search(query, num_results): 依据 SERPER/TAVILY/SEARXNG 的优先顺序进行网络检索，返回标题、链接、摘要和 page_content（若成功抓取）。
      • get_content(url): 针对单个 URL 提供 Markdown 格式的内容渲染，优先使用专门解析器，其它情况回落到通用 HTML 加载器。
    • 内容解析与渲染：
      • StackExchange、GitHub（Issues/Discussions）、Wikipedia、arXiv 的专用解析器与 Markdown 渲染，提供固定结构化输出，便于 LLM 处理。
      • universial HTML 加载器 nodriver_worker 提供的无头浏览器路径，支持断点与容错。
    • 安全与诊断：
      • 支持 KINDLY_DIAGNOSTICS 诊断开关，输出结构化诊断信息，便于调试与审计。
      • 对环境变量进行掩码，避免敏感信息泄露。
    • Docker/远端部署与多种传输协议支持，便于在不同客户端（本地、云、容器化环境）接入。

  • 安装与运行（概要）

    • 依赖与运行：遵循仓库 README 的“大流方案”启动，通常通过 UVX 进行工具环境的搭建与运行，具体方式请参考仓库的快速上手部分。
    • 必要配置：
      • 你需要配置一个网页检索提供者（Serper、Tavily 或 SearXNG 其中之一）。上述提供者的 API Key/URL 需通过环境变量设置：SERPER_API_KEY、TAVILY_API_KEY、SEARXNG_BASE_URL。
      • 其他环境变量（如 GITHUB_TOKEN、浏览器路径 KINDLY_BROWSER_EXECUTABLE_PATH）用于内容提取和渲染。
    • MCP 客户端配置：将 MCP 服务器注册到客户端配置中（见下方“服务器配置”部分的示例），以便客户端通过 MCP 调用 web_search 和 get_content。

  • 服务器配置（MCP 客户端配置示例，供参考，实际请根据你的环境替换占位符） server name: kindly-web-search command: uvx args: [ "--from", "git+https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server", "kindly-web-search-mcp-server", "start-mcp-server" ] env（可选，若使用本仓库示例需按需配置）: { "SERPER_API_KEY": "<SERPER_API_KEY>", "TAVILY_API_KEY": "<TAVILY_API_KEY>", "SEARXNG_BASE_URL": "<SEARXNG_BASE_URL>", "GITHUB_TOKEN": "<GITHUB_TOKEN>", "KINDLY_BROWSER_EXECUTABLE_PATH": "<PATH_TO_BROWSER>" }

  • 基本使用方法

    1. 在 MCP 客户端（如 Codex/Caga/Claude/Cursor 等）中，配置 Kindly Web Search MCP 服务器信息，确保服务器能通过所选传输协议与客户端通信。所需最少信息包括：
      • server name: kindly-web-search
      • command/args: 如上示例，以便客户端能够启动 MCP 服务器进程。
      • 允许设置环境变量以控制提供者、浏览器路径等参数。
    2. 设置提供者密钥或 URL（SERPER_API_KEY、TAVILY_API_KEY、SEARXNG_BASE_URL）等，确保 web_search 能正常获取结果。
    3. 在需要从网页获取单独内容时，使用 get_content(url) 工具获取相应的 Markdown 内容。
    4. 客户端调用时，采用 MCP 标准的 JSON-RPC 请求/响应格式，与服务端进行资源读取、工具调用和 Prompt 模板的渲染与获取。

  • 说明要点

    • MCP 服务端名称为 kindly-web-search，实际对接时请按该名称在客户端配置中引用。
    • 服务端支持多种传输协议，且在缺省时使用 stdio（与 MCP 客户端的标准 I/O 流整合）。
    • 安全性：不要在镜像中硬编码 API Key，统一通过环境变量传入。

  • 运行与测试注意

    • 仓库自带单元测试覆盖了服务端工具、内容解析、浏览器加载等核心组件，确保在运行环境具备依赖后可执行测试。
    • 部署时请确保本机或容器有可用的 Chromium 浏览器或等价浏览器二进制文件，并正确设置 KINDLY_BROWSER_EXECUTABLE_PATH。

服务器信息

访问项目