mcp-retrieval

这是什么

mcp-retrieval 是一个用 Go 编写的 Model Context Protocol 服务器。它以三个只读工具的形式，向任何兼容 MCP 的客户端（Claude Desktop、IDE 代理、自定义 LLM 应用）提供网络检索能力。底层使用 retrieval-go 库来搜索网络和抓取页面，并将结果以干净的 Markdown 形式返回，可直接交给模型使用。

该库不需要任何 API 密钥：网络搜索通过 DuckDuckGo Lite，图片搜索通过 Bing Images，页面抓取则先将 HTML 经过可读性提取器处理，再转换为 Markdown。为了在反机器人防护面前保持可靠，它在 TLS 层面模拟真实浏览器，并且可以轮换浏览器指纹和代理——参见检索引擎。

MCP SDK 支持的两种传输方式都可用，并且暴露完全相同的工具集：

• stdio — 客户端启动二进制文件并通过 stdin/stdout 通信（默认方式，适合桌面客户端）。

• http — 一个长期运行的流式 HTTP 服务器（适用于远程/共享部署）。

Related MCP server: mcp-web-calc

工具

这三个工具都被标注为只读。每个工具返回一个与其输出模式匹配的结构化 JSON 载荷；SDK 会将相同的 JSON 镜像到文本内容块中，供不读取 structuredContent 的客户端使用。

web_search

web_search_images

web_scrape

queries/urls 列表每次调用最多 max_queries（10）项。查询必须 ≤ 512 个字符；URL 必须 ≤ 2048 个字符且仅限 http/https。

结果与数量

每次调用都会在输入列表上扇出，并为每个查询/URL 返回一条结果，每条结果都有自己的 status——success、failed 或 timeout——因此部分失败时仍会返回成功的那部分条目。

count 是实际返回的条目数，它可能低于请求的 max_results / max_images：单个查询结果中的重复项会在应用上限之前被移除，而且上游可能本身就没有那么多条目。较小的 count 是正常结果，不是错误。

去重是按查询进行的，而不是跨查询。每个条目独立去重，因此同一调用中两个查询都找到的链接会出现在两个条目中——如果你需要，请自行对并集去重。

错误

请求级别的失败会以 isError: true 的工具结果和纯文本消息返回，而不是 JSON-RPC 错误——模型可以读取该消息并自行修正调用。逐条失败永远不会这样处理；它们会以 status: "failed" / "timeout" 的形式保留在载荷内部。

只有在输入在开始任何工作之前就被拒绝，或者调用中的每个条目都失败时，调用才会完全失败：

全失败消息刻意不区分超时与其他原因：混合批次可能同时因多种原因失败，而只要至少有一个条目存活，逐条 status 就已经携带了该细节。

已知限制

• web_scrape 仅处理 HTML。 页面会经过可读性提取器处理，这需要文章标记，因此 text/plain 响应不会产生任何内容，并以 status: "failed" 返回。原始文件托管是常见情况：raw.githubusercontent.com、github.com/.../raw/...、cdn.jsdelivr.net。请抓取渲染后的页面，而不是原始文件。

• web_search_images 的相关性无法保证。 对于某些查询，Bing Images 提供的页面并非结果集，但会被当作结果集解析——该工具随后会以 status: "success" 返回不相关的图片。请将图片结果视为尽力而为，在向用户展示之前先进行验证。

• 不支持 JavaScript。 页面按原样抓取；客户端渲染的内容对提取器不可见。

快速开始

安装

选择适合你的方式——所有方式都提供完全相同的服务器。

容器（无需 Go 工具链）：

docker pull ghcr.io/role1776/mcp-retrieval:latest

预编译二进制 — 从最新发布中获取适合你平台的压缩包，解压后将 mcp-retrieval 放到你的 PATH 中。

MCP Bundle — 对于支持安装 .mcpb 文件的客户端，从最新发布下载 mcp-retrieval_<version>_<os>_<arch>.mcpb 并用你的客户端打开。该 bundle 携带编译好的二进制文件，因此既不需要 Docker 也不需要 Go。请选择与你操作系统和 CPU 架构匹配的文件：一个 bundle 只包含一个原生二进制文件。

从源码构建：

go install github.com/Role1776/mcp-retrieval/app/cmd/mcp-retrieval@latest   # needs Go 1.25.5+

或者就地构建二进制文件（Go 模块位于 app/ 中）：

make build          # -> bin/mcp-retrieval

运行

# defaults: stdio transport, no configuration needed
./bin/mcp-retrieval

# with an explicit env file
./bin/mcp-retrieval -env /absolute/path/to/.env

唯一的标志是可选的：

连接 MCP 客户端（stdio）

将客户端指向构建好的二进制文件。Claude Desktop 配置示例：

{
  "mcpServers": {
    "retrieval": {
      "command": "/absolute/path/to/mcp-retrieval",
      "env": {
        "MAX_RESULTS": "20"
      }
    }
  }
}

env 块是可选的——仅 "command" 就足够了。

连接 MCP 客户端（容器）

在 stdio 上运行镜像。配置仍然通过 env 块传递，但 Docker 需要在命令行上用 -e 为每个变量命名，才能使其到达进程：

{
  "mcpServers": {
    "retrieval": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MAX_RESULTS",
        "-e", "DEFAULT_TIMEOUT_MS",
        "ghcr.io/role1776/mcp-retrieval:latest"
      ],
      "env": {
        "MAX_RESULTS": "20",
        "DEFAULT_TIMEOUT_MS": "5000"
      }
    }
  }
}

-i 是必需的——没有它，容器将没有 stdin，客户端会看到服务器立即退出。从 MCP Registry 安装的客户端会自行构建此调用，并提示输入 server.json 中声明的变量。

通过 HTTP 运行

设置 MCP_TRANSPORT=http，服务器将在 SERVER_PORT 上的 MCP_PATH 处监听（默认 http://localhost:8080/mcp）。

配置

所有内容都通过环境变量进行配置，每个值在启动前都会经过验证：非数字或非正数的值都会导致启动错误。限制之间的相互关系不会在启动时检查——请参阅 限制。环境中已有的变量优先于 .env 文件，因此 MCP 客户端的 env 块始终生效。每个字段都有合理的默认值，因此服务器可以在完全没有配置的情况下运行（stdio 传输）。

请参阅 .env.example 获取完整列表及其默认值，可直接复制到 .env。

MCP 服务器

向客户端通告的版本不可配置：它在构建时从 git 标签写入二进制文件。

HTTP 服务器（仅 http 传输）

HTTP 客户端和代理

配置代理后，每个出站请求都会在登录名后附加一个唯一的会话 ID，因此上游提供商会为每个请求轮换出口 IP。

限制

每个值都会单独检查——必须大于零——但 DEFAULT_*、MIN_* 和 MAX_* 三元组不会在启动时相互交叉检查。不一致的集合不会阻止服务器启动；它会在每个请求时进行协调：

• 调用方省略的值，或传入零或负数的值，会回退到匹配的 DEFAULT_*；

• 结果随后被限制在 [MIN_*, MAX_*] 范围内，因此大于其 MAX_* 的 DEFAULT_* 只会产生 MAX_*；

• 如果 MIN_* 超过 MAX_*，则以最大值为准。

因此，有效限制始终在配置的最大值之内，配置错误会降级为可工作的服务器，而不是启动失败。代价是它会静默降级：诸如 MAX_RESULTS=2 而不是 20 这样的拼写错误不会产生任何警告，只会悄悄产生更小的响应。当结果看起来被截断时，值得仔细检查这些值。

日志

架构

该项目遵循清晰的分层结构。依赖关系向内指向领域层，每一层通过接口与下一层通信。

app/                       the Go module: sources plus its build files
                           (Dockerfile, .dockerignore, .goreleaser.yaml)

cmd/mcp-retrieval/main.go  entry point: parse flags, load config, run app

internal/
  app/                     wiring + lifecycle (build server, run, graceful shutdown)
  config/                  config loading (.env → env vars → validate)
  domain/                  core types (Query, Link, Document, Snippet, Image) and errors
  dto/web/                 request/response shapes for the MCP tools
  transport/mcp/           MCP layer
    router/                registers every tool group on the MCP server
    web/                   tool handlers
    utils/                 schema helpers and error → tool-result mapping
  usecase/web/             business logic: validation, parallelism, timeouts, dedupe/limit/rerank
  adapter/web/             retrieval-go client wiring (search, images, scrape, proxy)
  pkg/                     reusable building blocks (mcpserver, server, logger, validator)

工具调用的请求流程：

MCP client → transport/mcp/web (handler) → usecase/web → adapter/web → retrieval-go → the web
                     ↑ maps errors               ↑ validates, fans out, limits results

搜索和抓取都会在输入列表上并发展开，并聚合每个项目的结果，每个结果都有自己的状态（success、failed、timeout）。只有当调用中的每个项目都失败时，该调用才会完全失败。

检索引擎

所有网络工作都委托给 retrieval-go，在 app/internal/adapter/web 中配置。值得了解：

• 来源。 网络搜索使用 DuckDuckGo Lite；图片搜索使用 Bing Images；页面抓取将原始 HTML 通过可读性提取器处理，并将主要文章转换为 Markdown（包括表格）。不需要搜索引擎 API 密钥。

• 浏览器模拟。 适配器启用了 WithBrowserRotation()，因此每个请求都从约 11 个真实浏览器配置文件中随机选择一个发送。每个配置文件都将真实的 TLS/JA3 指纹（通过 uTLS）与匹配的 User-Agent 和客户端提示头配对——Chrome 133/131/120（Windows/macOS/Linux）、Edge 131、Firefox 120（Windows/macOS）、Safari 18.4（macOS）和 iOS 18.4 Safari。这使得流量看起来像普通浏览器，而不是 Go HTTP 客户端，这正是保持免费来源可访问的原因。

• 代理轮换。 配置 PROXY_HOST 后，适配器会安装一个代理工厂，在每个请求的代理用户名后附加唯一的 session-<id>。使用基于会话的住宅/轮换代理提供商时，这会为每个请求提供新的出口 IP，分散负载并避免速率限制。没有代理时，请求直接发出。

• 响应处理。 响应会被透明解压（gzip、br、zstd、deflate），并禁用 keep-alive（WithDisableKeepAlive()），这样连接池不会在请求之间固定单个指纹/IP。

这些都不需要配置即可工作——上述默认值会自动应用。只有代理凭据是可选的附加项。

开发

所有 Go 代码都位于 app/ 中，因此可以从仓库根目录使用 makefile，或者向工具链传递 -C app：

make build          # compile the binary
make test           # run tests

go -C app build ./...      # compile everything
go -C app test ./...       # run tests
go -C app vet ./...        # static checks

有关拉取请求指南，请参阅 CONTRIBUTING.md。

许可证

根据 MIT License 发布。