serpapi-agent-toolkit

CI License: MIT

Context-cheap SerpApi search for AI agents: a CLI and a Claude Code skill, built as complements to SerpApi's official serpapi-mcp server, not replacements.

The idea is simple. An MCP server injects its tool schema into the model's context on every turn, whether you search or not. A CLI is a binary on PATH that costs nothing until you call it, and it can trim each response down to the fields you actually want. For stateless, high-frequency search inside a coding loop, that gap adds up.

Measured, same query, same serpapi library

SerpApi MCP serp CLI
Standing cost, every turn 771 tokens (tool schema) ~0 (binary) + ~110 if the skill is loaded
Discovery, once engine resource google.json = 5,816 tokens --help = ~290 tokens
Per call (google, 10 results) 6,047 (complete, default) / 4,577 (compact) 351 (--fields title,link)

About 17x smaller per call than the MCP default, 13x smaller than its compact mode. The full method, with the honest caveats, is in the dev.to write-up.

The two pieces

Piece What When
cli/ serp, a zero-dependency Bun + TypeScript CLI that returns only the fields you ask for, as one compiled binary. High-frequency, stateless one-shot search in a coding loop, where an always-loaded MCP schema taxes every turn.
skills/searching-with-serpapi A Claude Code skill: the procedure for searching well (engine by intent, compact vs complete, operators, pagination, dedup and cite, when not to search). ~110 tokens until triggered. Any agent with a SerpApi search capability that should use it well and cheaply.

MCP (or this CLI) provides the capability; the skill provides the how-to on top. Use SerpApi's MCP server for hosted, multi-client, stateful connections; use serp for cheap stateless calls; let the skill make either one easy to use correctly.

Quick start

cd cli && bun install && bun run build
export SERPAPI_API_KEY=your_key          # or SERP_API_KEY, both are accepted

# stateless search, trimmed to the fields you want
./dist/serp search "remote rails jobs" --engine google_jobs --num 5 --fields title,link

# localized results: geo flags only go on the wire when set
./dist/serp search "best noise cancelling headphones" --engine google --location Brazil --gl br --hl pt --fields title,link

Install the skill into Claude Code:

cp -r skills/searching-with-serpapi ~/.claude/skills/

Develop

cd cli
bun test            # 37 unit tests, fully offline (no key, no network)
bun run typecheck
bun run build       # single self-contained binary at dist/serp

The URL builder, argument parser, and result shaping are pure functions; the network call and the run() entry take an injected fetch and injected streams, so the whole suite runs offline.

License

MIT. See LICENSE.