OwnSERP

OwnSERP

一个用于 Serper.dev 搜索 API 的 MCP 服务，按次调用核算额度。

状态

1.0 版已稳定。每次发布都会在完整的本地检查通过后，从带标签的提交构建。语义化版本承诺适用于命令行、配置档案架构、账本格式和工具结果结构，不适用于 ownserp-core crate 的 Rust API，因此次要版本可能会重命名其中的公开项。从 1.0 版起，命令界面、配置架构、账本格式和工具结果结构遵循语义化版本规则：对其中任一项的破坏性更改都需要升级主版本，新增工具、标志或设置需要升级次要版本，修复则升级修订版本。CHANGELOG.md 记录了每项更改。

目录

• 概述
• 要求
• 安装
• 快速开始
• 连接客户端
• API 密钥
• 工具
• 响应结构和字段预设
• 成本核算和账本
• 配置
• HTTP 部署
• 安全性
• 故障排除
• 开发
• 分发
• 支持
• 贡献
• 许可证

概述

OwnSERP 将 Serper.dev 搜索端点作为 MCP（Model Context Protocol）工具提供。模型可以通过一个本地服务搜索网页、图片、新闻、地点、地图、视频、购物、学术论文、专利、评论和 Lens，提取页面内容、解析地点名称，并读取自身的支出。

它专为消耗计量额度的 Agent 构建。每个工具说明都标明价格，每个结果都包含成本对象，本地账本会记录每次调用。在调用产生任何费用之前，服务可以检查单次调用上限和会话预算；如果超过任一限制，就会拒绝调用。除非你通过配置档案中的 per_call_credit_ceiling 和 session_budget_credits，或环境变量 OWN_SERPER_PER_CALL_CREDIT_CEILING 和 OWN_SERPER_SESSION_BUDGET_CREDITS 设置限制，否则两者默认都关闭。结果面向模型而非浏览器进行整理：会剔除不可见字符，对长文本进行截断并加以标记，省略缺失字段，并固定键的顺序。

该服务是一个独立二进制文件，无需语言运行时。它使用 MCP 修订版 2026-07-28，并响应使用 2025-11-25 版本的客户端。默认通过 stdio 运行，也可通过带有 bearer token 门禁的 Streamable HTTP 运行。

要求

• 运行已发布的二进制文件：无需运行时或工具链。预构建二进制文件支持 macOS、Linux 和 Windows。
• 从源代码构建：需要 Rust 1.89 或更高版本，rust-toolchain.toml 中固定为 1.99.1。
• 需要 Serper.dev 账号和 API 密钥：https://serper.dev/api-keys。
• 需要支持通过 stdio 使用 MCP 的客户端，或用于 Streamable HTTP 传输的任意 HTTP 客户端。

安装

所有安装方式都使用预构建二进制文件：无需 Rust 工具链，也无需编译。

发布压缩包支持 macOS ARM64 和 x86_64、使用 glibc 的 Linux x86_64、使用 glibc 的 Linux ARM64、使用静态 musl 的 Linux x86_64 和 ARM64，以及 Windows x86_64。

npm

npx @devops-infinity/ownserp serve

该软件包会在安装时下载适用于当前平台的压缩包，根据发布校验和对其进行校验，然后运行二进制文件。需要 Node 22 或更高版本。

Homebrew

brew install devops-infinity/tap/ownserp

macOS 和 Linux 都会安装发布版二进制文件。每次发布后都会手动更新 tap，因此可能比发布晚几分钟。

Shell 安装程序

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/devops-infinity/ownserp/releases/latest/download/ownserp-installer.sh | sh

在 Windows 上使用 PowerShell：

powershell -ExecutionPolicy Bypass -c "irm https://github.com/devops-infinity/ownserp/releases/latest/download/ownserp-installer.ps1 | iex"

Release archive

VERSION=1.3.1
BASE="https://github.com/devops-infinity/ownserp/releases/download/v$VERSION"
TARGET=x86_64-unknown-linux-gnu
curl -LO "$BASE/ownserp-$TARGET.tar.gz"
curl -LO "$BASE/ownserp-$TARGET.tar.gz.sha256"
sha256sum -c "ownserp-$TARGET.tar.gz.sha256"
tar -xzf "ownserp-$TARGET.tar.gz"
install -m 0755 "ownserp-$TARGET/ownserp" ~/.local/bin/ownserp

在 macOS 上，将 TARGET 设置为 aarch64-apple-darwin 或 x86_64-apple-darwin；在对应平台上，设置为 aarch64-unknown-linux-gnu、x86_64-unknown-linux-musl 或 aarch64-unknown-linux-musl；在 Windows 上，使用 x86_64-pc-windows-msvc 对应的 .zip 文件。

二进制文件可按需输出 shell 补全脚本和手册页，命令分别为 ownserp completions <shell> 和 ownserp man。请将它们安装到 shell 和手册阅读器查找的位置：~/.local/share/bash-completion/completions/、fpath 中的某个目录、~/.config/fish/completions/ 和 ~/.local/share/man/man1/。

配置了仓库密钥 MINISIGN_KEY 后，每次发布都会使用 minisign 为 sha256.sum 签名。要检查下载内容，请先使用此仓库中的公钥验证签名，然后对照该文件检查压缩包：

minisign -Vm sha256.sum -P RWSPyQWAsXwP5vjgAFI/PAAtbFAd5tA4BlhyFrT+MCPNmE2J+jgT26kC
grep "ownserp-x86_64-unknown-linux-gnu.tar.gz" sha256.sum | sha256sum --check

容器

docker run --rm -p 127.0.0.1:8777:8777 \
  -e SERPER_API_KEY -e OWN_SERPER_BEARER_TOKENS \
  -e OWN_SERPER_ALLOWED_HOSTS=127.0.0.1,localhost \
  ghcr.io/devops-infinity/ownserp:latest

该镜像提供 Streamable HTTP，且在没有 bearer token 的情况下会拒绝公开绑定，因此必须设置这两个变量。OWN_SERPER_ALLOWED_HOSTS 必须包含客户端发送的每个 Host，因为镜像绑定到 0.0.0.0，而根据该地址生成的允许列表无法匹配任何实际的 Host；请将公开主机名或代理发送的名称添加到同一个列表中。该软件包是公开的，因此执行 docker pull 无需登录。

Windows

使用上文的 PowerShell 安装程序，或从发布页面下载 ownserp-x86_64-pc-windows-msvc.zip，解压出 ownserp.exe，并将其所在文件夹添加到 PATH。如果客户端配置无法解析该名称，请使用 ownserp.exe 的绝对路径。

MCPB bundle

该 bundle 仅包含 Linux x86_64 二进制文件。在其他架构上，请改为安装对应平台的压缩包。

从发布页面下载 ownserp-<version>.mcpb，并在支持 MCP Bundles 的客户端中打开。该 bundle 会提示输入 API 密钥，并将其存储在操作系统密钥链中。

快速开始

export SERPER_API_KEY="your key"
npx @devops-infinity/ownserp doctor
npx @devops-infinity/ownserp serve

第一条命令为当前 shell 设置密钥。第二条命令会打印解析后的设置、经过掩码处理的密钥来源，以及两个 Serper 主机的响应。第三条命令通过 stdio 启动服务，这是 MCP 客户端会启动的命令；服务会持续运行，直到客户端将其停止。

要连接客户端，请按下一节所示添加服务。

连接客户端

每个客户端都会将 ownserp serve 作为 stdio 进程运行，并在环境中传入 SERPER_API_KEY。如果桌面客户端无法在 PATH 中解析 ownserp，请使用 command -v ownserp 输出的绝对路径。

Claude Code

claude mcp add --scope project ownserp -- ownserp serve

或者，在项目根目录提交 .mcp.json：

{
  "mcpServers": {
    "ownserp": {
      "command": "ownserp",
      "args": ["serve"]
    }
  }
}

Claude Desktop

将以下内容添加到 claude_desktop_config.json。在 macOS 上，该文件位于 ~/Library/Application Support/Claude/；在 Windows 上，位于 %APPDATA%\Claude\。请使用已安装二进制文件的绝对路径，因为桌面应用不会继承 shell 的 PATH：

{
  "mcpServers": {
    "ownserp": {
      "command": "/absolute/path/to/ownserp",
      "args": ["serve"],
      "env": { "SERPER_API_KEY": "your key" }
    }
  }
}

npm 软件包会为当前平台安装预构建的二进制文件。如果客户端继承了你的 PATH，请将 command 指向 ownserp；否则，请将其指向 command -v ownserp 输出的绝对路径。

OpenAI Codex CLI

在 ~/.codex/config.toml 中，或项目的 .codex/config.toml 中：

[mcp_servers.ownserp]
command = "ownserp"
args = ["serve"]
env_vars = ["SERPER_API_KEY"]

env_vars 会从环境中传入变量，因此密钥不会出现在命令行中。

Command Code

commandcode mcp add-json --scope project ownserp '{"type":"stdio","command":"ownserp","args":["serve"]}'

Cursor

在 ~/.cursor/mcp.json 中，或单个项目的 .cursor/mcp.json 中：

{
  "mcpServers": {
    "ownserp": {
      "command": "ownserp",
      "args": ["serve"],
      "env": { "SERPER_API_KEY": "your key" }
    }
  }
}

Windsurf (Cascade)

在 Linux 和 macOS 上，文件位于 ~/.config/devin/mcp_config.json；在 Windows 上，位于 %APPDATA%\devin\mcp_config.json：

{
  "mcpServers": {
    "ownserp": {
      "command": "ownserp",
      "args": ["serve"],
      "env": { "SERPER_API_KEY": "your key" }
    }
  }
}

VS Code

从命令面板运行 MCP: Add Server，或将 .vscode/mcp.json 添加到工作区：

{
  "servers": {
    "ownserp": {
      "type": "stdio",
      "command": "ownserp",
      "args": ["serve"],
      "env": { "SERPER_API_KEY": "your key" }
    }
  }
}

Zed

在 settings.json 中：

{
  "context_servers": {
    "ownserp": {
      "command": "ownserp",
      "args": ["serve"],
      "env": { "SERPER_API_KEY": "your key" }
    }
  }
}

其他 MCP 客户端

使用 stdio，命令为 ownserp，参数为 serve；并在客户端的环境块中，或客户端继承的 shell 中设置 SERPER_API_KEY。

API 密钥

三种来源均可使用，进程环境变量的优先级高于密钥链。

• 环境变量，可在 shell 或客户端的 env 块中设置：

export SERPER_API_KEY="your key"

• OS 密钥链，从 stdin 读取，避免密钥进入 shell 历史记录：

printf '%s' "$SERPER_API_KEY" | ownserp config set-api-key

• 客户端 JSON 配置，由客户端注入其持有的 env 块。

密钥绝不会从命令行参数读取，不会写入配置文件，也绝不会以未遮盖的形式打印。在 Linux 上，密钥链存储使用 Secret Service，因此必须运行桌面会话总线；在无头服务器上，请改为设置 SERPER_API_KEY。请在 https://serper.dev/api-keys 为每个项目或 Agent 使用一个专用密钥，因为密钥无法限制到更低的支出额度。

工具

工具列表中的每项工具描述都会注明价格，方便模型在使用前规划预算。

• serper_search，1 个额度。网页结果，包含知识图谱、答案框和相关搜索。
• serper_images，1 个额度；当 num 大于 10 时为 2 个额度。图片结果，包含尺寸和来源。
• serper_news，1 个额度。带日期的新闻结果。
• serper_places，1 个额度。按 Serper 位置名称筛选的本地商家。
• serper_maps，3 个额度。以 @lat,lng,zoomz 格式指定地图视口范围的地点。
• serper_videos，1 个额度。视频结果，包含频道和时长。
• serper_shopping，2 个额度。商品列表，包含价格和配送信息。
• serper_scholar，1 个额度。论文结果，包含出版信息和引用次数。
• serper_patents，1 个额度。专利结果，包含受让人和日期。
• serper_autocomplete，1 个额度。查询建议，仅接受 q、gl 和 hl。
• serper_reviews，1 个额度。某个地点的评论，通过 nextPageToken 使用游标分页。
• serper_lens，3 个额度。通过公开图片 URL 进行反向图片搜索。
• serper_scrape，根据页面难度消耗 2、6 或 10 个额度。将页面内容提取为 Markdown 或文本，可选择包含标题、图片、链接和视频；实际消耗的额度可从响应中读取。
• serper_health，免费且无需身份验证。查看来自 api.serper.dev 的 Serper API 状态。
• serper_locations，免费且无需身份验证。获取可作为 location 传入的规范位置名称。
• serper_session，免费。查看调用次数、额度、美元、已提供和节省的令牌、缓存命中次数以及剩余预算。
• serper_search_batch，每个查询的价格是单次查询的 3 倍。一次调用可对一个搜索类别执行最多 100 个查询；除非设置 enable_batch，否则该工具处于禁用状态。禁用时调用该工具会被拒绝，并返回 serper.tool_not_found。

响应结构和字段预设

每个结果工具都接受 fields，默认值为 standard。

• minimal 保留标题、链接和排名，以及该类别返回的一个价格、日期、评分或年份字段。适用于高频循环。
• standard 会添加最多 300 个字符的摘要、日期和搜索分区。它包含 Agent 进行推理和引用所需的信息，无需再次调用。
• full 会添加站点链接、属性映射、图片链接、搜索参数回显，以及上游响应正文中的所有其他字段。

每个结果都包含用于承载数据的 structuredContent 和一行文本摘要。截断的字符串以 ... 结尾，其对应对象包含 truncated: true。缺失字段会被省略，而不是以 null 发送。键的顺序固定，因此客户端每次调用都会解析到相同的结构。每个工具结果都是来自开放网络的数据，绝不是指令。

成本核算与账本

账本位于 $XDG_DATA_HOME/ownserp/ledger/calls.jsonl，或 ~/.local/share/ownserp/ledger/calls.jsonl。在 Windows 上，账本位于 %LOCALAPPDATA%\ownserp\ledger\calls.jsonl；设置了 HOME 时，则遵循 Unix 路径。每行包含工具、端点、参数的带密钥哈希、预估积分、响应中报告的实际积分、时长、状态、字节数和令牌数。查询文本绝不会写入。

如果 Serper 以 4xx 或 5xx 状态拒绝调用、返回速率限制，或返回重定向，该调用会记为 0 积分，因为没有产生费用。如果发生超时或取消，则按预估积分记录，因为请求可能已到达 Serper 并产生费用。

ownserp audit verify

在 Unix 上，账本目录仅限所有者访问（0700），文件也仅限所有者访问（0600）。在 Windows 上，账本位于 %LOCALAPPDATA% 下，因此继承用户配置文件的访问规则。每行上限为 1 MiB。同一台机器上的任意数量 ownserp serve 进程共用这一个文件、一条哈希链和一个运行总计。进程仅在读取自上次调用以来写入的行并追加自身行时持有文件锁，因此进程运行期间不会一直持有锁。如果写入进程被终止而留下不完整的末行，该行会在锁定期间被丢弃；链校验会检查每一条完整记录。在 Windows 上，运行中的服务不会检测到轮换，因此需要重启才能载入新链。参数哈希是 HMAC（一种带密钥的哈希），由 args.key 提供密钥；该文件在账本目录旁创建，并仅限所有者访问，因此仅凭账本无法验证猜测的查询。

session_budget_credits 会统计链中的所有积分，无论记录由哪个进程写入。其他进程已预留但尚未写入的积分对此检查不可见，因此预算最多可能超出运行进程数乘以每次调用的积分上限。只有设置了上限时，此界限才成立。如果没有设置上限，则超出量为进程数乘以最大单次预留积分；对于 100 条查询的 maps 或 lens 批次，该值为 900 积分。响应缓存和 OWN_SERPER_QPS 上限仍按进程分别生效：每个进程都有自己的缓存和出站请求速率。若需要为客户端使用单独的账本，仍可设置 OWN_SERPER_LEDGER_DIR。

要关闭账本但保留文件，请运行 ownserp audit rotate。该命令会校验哈希链，并在原文件旁以时间戳为名归档文件。每个运行中的服务都会在下次写入时开启一条新链。

美元金额根据套餐等级计算：starter（默认）、standard、scale、ultimate，或搭配 SERPER_USD_PER_1K 使用的 custom。

配置

环境变量：

• SERPER_API_KEY
• SERPER_USD_PER_1K
• OWN_SERPER_PROFILE
• OWN_SERPER_BIND
• OWN_SERPER_QPS，客户端每秒查询次数上限
• OWN_SERPER_CACHE_TTL_SECS
• OWN_SERPER_LEDGER_DIR
• OWN_SERPER_BEARER_TOKENS
• OWN_SERPER_ALLOWED_HOSTS
• OWN_SERPER_HTTP_QPS，HTTP 模式下的全局入站请求上限；未设置或设为 0 时关闭
• OWN_SERPER_LOG_FORMAT，设为 json 后，每行日志输出一个 JSON 对象

配置文件位于 $XDG_CONFIG_HOME/ownserp/profile.toml，或 ~/.config/ownserp/profile.toml。在 Windows 上，如果未设置 HOME，则位于 %APPDATA%\ownserp\profile.toml：

version = 1
pack = "starter"
usd_per_1k = 1.0
qps = 50
cache_ttl_secs = 0
cache_max_bytes = 16777216
ledger_dir = "/absolute/path/to/ownserp-ledger"
per_call_credit_ceiling = 10
session_budget_credits = 500
enable_batch = false
http = false
bind = "127.0.0.1:8777"
request_timeout_secs = 30
http_qps = 0

version 是配置文件的架构版本。目前为 1；如果配置文件声明了更新的版本，程序会直接拒绝加载。

ledger_dir 必须使用绝对路径。该文件是 TOML 文档，因此 ~ 或变量会按字面形式存储，不会展开。

session_budget_credits 统计当前账本链中写入的所有积分，重启后仍会累计；ownserp audit rotate 会重新开始计数。allowed_hosts 列出 HTTP 模式接受的 Host 名称；留空则根据绑定地址推导。

如果自定义套餐未设置 usd_per_1k，由于费率未知，报告只会显示积分，不会显示美元金额。

缓存默认关闭。将 cache_ttl_secs 设为大于 0 的值即可启用；命中缓存时会返回 cacheHit: true，且不扣费。设置了 tbs 的调用会跳过缓存。

ownserp doctor 会打印解析后的设置、遮盖密钥、注明密钥来源，并探测两个主机。ownserp config show 会打印密钥来源、遮盖后的密钥、积分套餐、账本目录和配置文件路径。

HTTP 部署

OWN_SERPER_BEARER_TOKENS="a random value of at least 32 characters" \
  ownserp serve --http --bind 127.0.0.1:8777

/healthz 无需身份验证。只要设置了 OWN_SERPER_BEARER_TOKENS，访问 /readyz 和 /metrics 就需要 Bearer 令牌；其他所有路径都是 MCP 端点。服务器拒绝绑定到非环回地址而未提供令牌的配置，也拒绝长度不足 32 个字符的令牌。服务器会在每个受保护的路由上检查 Host 标头是否在允许列表中，将请求正文限制为 1 MiB，并要求正文在 30 秒内到达；最多接受 256 个连接；在消耗全局速率限制额度前先检查 Bearer 令牌；/readyz 不受该限流器限制；同时最多处理 128 个请求；根据 request_timeout_secs 和重试次数为每个请求设定截止时间，截止时间到达后取消调用；拒绝携带 Origin 标头的请求；并为每个响应设置 x-content-type-options: nosniff 和 cache-control: no-store。同一服务器上的所有 Bearer 令牌共用该服务器的账本、会话预算和缓存。在代理后部署时，请在 OWN_SERPER_ALLOWED_HOSTS 中列出代理发送的名称，并让代理自行执行标头和空闲超时限制。

安全

服务器持有一个 API 密钥，仅通过 TLS 向 Serper 发送查询，且不会发送遥测数据。结果均视为不可信文本。SECURITY.md 说明了报告流程，威胁模型说明了资产、信任边界、控制措施和剩余风险。

故障排查

每个错误都包含一个稳定的代码、一条消息、一种解决方法；对于网络故障，还会提供最多三个经过净化的原因，用于说明 DNS、TLS 或连接问题。ownserp 成功时退出码为 0，运行时故障时为 1，用法错误时为 2。未配置密钥或 Serper 健康检查失败时，ownserp doctor 退出码为 1；如果账户端点未报告余额，则会显示该情况，但不会视为失败。错误代码及其修复方法如下：

• serper.auth_missing。未配置密钥。设置 SERPER_API_KEY，或运行 ownserp config set-api-key。
• serper.auth_failed。Serper 拒绝了该密钥。请在 https://serper.dev/api-keys 检查密钥。
• serper.rate_limited。上游速率限制或信用额度余额导致调用被阻止。Serper 不会发布重试标头，服务端也不会重试 429 错误。
• serper.budget_refused。调用上限或会话预算将被超出。请在配置文件中调高上限，或降低 num。
• serper.bad_request。某个参数未通过验证。消息会指出相应字段。
• serper.tool_not_found。该工具不在此配置的列表中。请调用 tools/list，并为批处理工具设置 enable_batch。
• serper.config_error。某项设置格式错误。ownserp doctor 会显示每个解析后的值及其来源。
• serper.keychain_error。操作系统密钥链不可用。在无头主机上使用 SERPER_API_KEY。
• serper.upstream_failed。重试后，Serper 或网络仍然失败。请检查 https://serper.betteruptime.com。
• serper.cancelled。客户端取消了请求。
• serper.internal_error。发生了意外的本地故障。重试一次，然后在提交问题时附上该消息。

开发

此路径需要 Rust 1.89 或更高版本，并在 rust-toolchain.toml 中固定为 1.99.1。

cargo install --path crates/ownserp --locked
tools/verify.sh

tools/verify.sh 会在本地运行完整检查：格式化、检查、将警告视为错误的 clippy、测试、文档测试、文档、公告检查、依赖项策略、未使用的依赖项、80％ 的行覆盖率下限，以及对代码树和 git 历史记录的密钥扫描。缺少相应工具的检查会标记为跳过；设置 OWN_SERPER_STRICT_GATE=1 后，任何跳过都会导致失败；发布流程会以此方式运行。

发布构建本身会在推送 v* 标签时，通过 .github/workflows/release.yml 在原生运行器矩阵上执行。

本地生命周期：

• tools/reinstall.sh 会构建二进制文件并将其安装到 ~/.local/bin。
• tools/release.sh --prepare 会递增版本号；--package 会构建归档文件和校验和。
• tools/publish-npm.sh 会发布 npm 包；tools/npm-auth-setup.sh 会存储令牌，使其无需 OTP。
• tools/registry-auth.sh 会使用当前 shell 中已有的环境变量刷新 GitHub、npm、crates.io、MCP Registry 和 ghcr 会话，因此发布期间无需向任何注册表请求登录。
• tools/install-hooks.sh 会让 git 使用本地钩子：每次提交前进行密钥扫描，每次推送前运行完整检查。
• RELEASING.md 是发布操作手册。
• docs/benchmark.md 对比了实时工具表面与 Python Serper MCP 服务，并记录了实测结果。

分发

• crates.io：ownserp 和 ownserp-core。
• npm：@devops-infinity/ownserp。
• Homebrew tap：devops-infinity/tap。
• MCP Registry：io.github.devops-infinity/ownserp。
• GitHub 发布：macOS ARM64 和 x86_64、Linux x86_64 和 ARM64（glibc）、Linux x86_64 和 ARM64（静态 musl）以及 Windows x86_64 的归档文件，每个文件都附有校验和；此外还有 shell 安装程序、PowerShell 安装程序和 Linux MCPB 包。
• 容器镜像：ghcr.io/devops-infinity/ownserp，公开。
• 此仓库中的清单：server.json、mcpb/manifest.json 和 Dockerfile。

支持

如有疑问、发现错误或需要提出功能请求，请在 https://github.com/devops-infinity/ownserp/issues 提交问题。安全问题请通过 SECURITY.md 中的私密渠道报告，切勿在问题中披露。

贡献

欢迎在 https://github.com/devops-infinity/ownserp 提交问题和拉取请求。提交拉取请求前，请运行 tools/verify.sh；只有通过检查后，更改才会合并。发布版本前，请阅读 RELEASING.md。

结果来自 Google，提供方为 Serper。下游用户仍须履行 Serper 条款规定的署名义务。

许可证

MIT OR Apache-2.0。请参阅 LICENSE-MIT 和 LICENSE-APACHE。