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/re

... [View full README on GitHub](https://github.com/devops-infinity/ownserp#readme)