OwnSERP

OwnSERP

An MCP server for the Serper.dev search API, with per-call credit accounting.

Status

Stable at 2.0. Every release ships from a tagged commit after the full local gate passes. The semantic version promise covers the command line, the profile schema, the ledger format, and the tool result shape. The Rust API of the ownserp-core crate is not covered by it, so a minor release may rename a public item there. From 1.0, the command surface, the configuration schema, the ledger format, and the tool result shape follow semantic versioning: a breaking change to any of them takes a major version, a new tool, flag, or setting takes a minor version, and a fix takes a patch. CHANGELOG.md records every change.

Contents

• Overview
• Requirements
• Installation
• Upgrading
• Quick start
• Connect a client
• API key
• Tools
• Response shape and field presets
• Example
• Cost accounting and the ledger
• Configuration
• HTTP deployment
• Security
• Troubleshooting
• Development
• Distribution
• Support
• Contributing
• License

Overview

OwnSERP exposes the Serper.dev search endpoints as MCP (Model Context Protocol) tools. A model can search the web, images, news, places, maps, videos, shopping, scholar, patents, reviews, and lens, extract a page, resolve a location name, and read its own spend, all through one local server.

It is built for agents that spend metered credits. Every tool description states its price, every result carries a cost object, and a local ledger records each call. Before a call spends anything, the server can check a per-call ceiling and a session budget and refuse the call when either would be passed. Both are off until you set them, through per_call_credit_ceiling and session_budget_credits in the profile, or OWN_SERPER_PER_CALL_CREDIT_CEILING and OWN_SERPER_SESSION_BUDGET_CREDITS in the environment. Results are shaped for a model rather than for a browser: invisible characters are stripped, long text is capped and marked, absent fields are omitted, and key order is fixed.

The server is one binary and needs no language runtime. It speaks MCP revision 2026-07-28 and answers clients on 2025-11-25. It runs over stdio by default, or over Streamable HTTP with a bearer token gate.

Requirements

• To run a published binary: no runtime, no toolchain. Prebuilt binaries cover macOS, Linux, and Windows.
• To build from source: Rust 1.89 or newer, pinned to 1.99.1 in rust-toolchain.toml.
• A Serper.dev account and API key from https://serper.dev/api-keys.
• A client that speaks MCP over stdio, or any HTTP client for the Streamable HTTP transport.

Installation

Every install path uses a prebuilt binary: no Rust toolchain and no compile step.

Release archives cover macOS ARM64 and x86_64, Linux x86_64 with glibc, Linux ARM64 with glibc, Linux x86_64 and ARM64 with static musl, and Windows x86_64.

npm

npx @devops-infinity/ownserp serve

The package downloads the archive for the current platform on install, checks it against the release checksum, and runs the binary. Node 22 or newer.

Homebrew

brew install devops-infinity/tap/ownserp

macOS and Linux both install the release binary. The tap is updated by hand after each release, so it can lag the release by a few minutes.

Shell installer

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

On Windows, in PowerShell:

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

Release archive

VERSION=2.4.0

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

Set TARGET to aarch64-apple-darwin or x86_64-apple-darwin on macOS, aarch64-unknown-linux-gnu or x86_64-unknown-linux-musl or aarch64-unknown-linux-musl on those platforms, and use the .zip file with x86_64-pc-windows-msvc on Windows.

The binary prints its shell completions and manual page on demand with ownserp completions and ownserp man. Install them where your shell and manual reader look, under ~/.local/share/bash-completion/completions/, a directory on fpath, ~/.config/fish/completions/, and ~/.local/share/man/man1/.

When the MINISIGN_KEY repository secret is configured, each release signs sha256.sum with minisign. To check a download, verify the signature against the public key in this repository, then check the archive against the file:

minisign -Vm sha256.sum -P RWSPyQWAsXwP5vjgAFI/PAAtbFAd5tA4BlhyFrT+MCPNmE2J+jgT26kC

grep "ownserp-x86_64-unknown-linux-gnu.tar.gz" sha256.sum | sha256sum --check

Container

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

The image serves Streamable HTTP and refuses a public bind without a bearer token, so both variables are required. OWN_SERPER_ALLOWED_HOSTS must name every Host a client sends, because the image binds 0.0.0.0 and the allowlist derived from that address matches no real Host; add the public hostname, or the name the proxy sends, to the same list. The package is public, so docker pull needs no login.

Windows

Use the PowerShell installer above, or download ownserp-x86_64-pc-windows-msvc.zip from the release page, extract ownserp.exe, and put the folder on your PATH. A client configuration that cannot resolve the name uses the absolute path to ownserp.exe.

MCPB bundle

The bundle carries the Linux x86_64 binary only. On another architecture, install the archive for that platform instead.

Download ownserp- .mcpb from the release page and open it in a client that supports MCP Bundles. The bundle asks for the API key and stores it in the OS keychain.

Upgrading

ownserp update asks GitHub for the latest release and prints the command that fits this install: brew upgrade ownserp, cargo install --locked ownserp, the npm global install, or the container pull. It checks and reports only, so the upgrade runs through the channel you installed with and that channel's own signing and review stay in force. ownserp update --json gives current, latest, updateAvailable, and command for scripts. The check calls api.github.com and nothing else, and the server itself still sends no telemetry.

Quick start

export SERPER_API_KEY="your key"

npx @devops-infinity/ownserp doctor npx @devops-infinity/ownserp serve

The first command sets the key for the shell. The second prints the resolved settings, the key source with the key masked, and the answer from both Serper hosts. The third starts the server on stdio, which is the command an MCP client launches, so it keeps running until the client stops it.

To connect a client, add the server as shown in the next section.

Connect a client

Every client runs ownserp serve as a stdio process and passes SERPER_API_KEY in the environment. When a desktop client cannot resolve ownserp on its PATH, use the absolute path printed by command -v ownserp.

Claude Code

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

Or commit a .mcp.json at the project root:

{

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

Claude Desktop

Add this to claude_desktop_config.json, at ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows. Use the absolute path to the installed binary, because a desktop application does not inherit the shell PATH:

{

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

The npm package installs the prebuilt binary for the current platform. Point command at ownserp when the client inherits your PATH, or at the absolute path command -v ownserp prints when it does not.

OpenAI Codex CLI

In ~/.codex/config.toml, or a project .codex/config.toml:

[mcp_servers.ownserp]

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

env_vars passes the variable from the environment, so the key never enters a command line.

Command Code

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

Cursor

In ~/.cursor/mcp.json, or .cursor/mcp.json for one project:

{

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

Windsurf (Cascade)

In ~/.config/devin/mcp_config.json on Linux and macOS, or %APPDATA%\devin\mcp_config.json on Windows:

{

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

VS Code

Run MCP: Add Server from the Command Palette, or add .vscode/mcp.json to the workspace:

{

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

Zed

In settings.json:

{

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

Other MCP clients

Use stdio with command ownserp and argument serve, and set SERPER_API_KEY in the client's environment block or in the shell the client inherits.

API key

Three sources work, and the process environment wins over the keychain.

• Environment variable, in the shell or in the client's env block:

export SERPER_API_KEY="your key"

• OS keychain, read from stdin so the key does not enter shell history:

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

• Client JSON config, where the client injects the env block it holds.

The key is never read from a command line argument, never written to the profile file, and never printed unmasked. On Linux the keychain store is Secret Service, so a desktop session bus must be running; on a headless server, set SERPER_API_KEY instead. Use one named key per project or agent at https://serper.dev/api-keys, because a key cannot be scoped to a smaller spend.

Tools

Every tool description in the tool list states the price, so a model can budget before spending.

• serper_search, 1 credit. Web results with knowledge graph, answer box, and related searches.
• serper_images, 1 credit, 2 when num is above 10. Image results with dimensions and source.
• serper_news, 1 credit. Dated news results.
• serper_places, 1 credit. Local businesses filtered by a Serper location name.
• serper_maps, 3 credits. Places anchored to a map viewport in @lat,lng,zoomz form.
• serper_videos, 1 credit. Video results with channel and duration.
• serper_shopping, 2 credits. Product listings with price and delivery.
• serper_scholar, 1 credit. Papers with publication info and citation counts.
• serper_patents, 1 credit. Patents with assignee and dates.
• `ser