serper-dev-mcp

A local Model Context Protocol server for the working Serper.dev Google search and web scraping APIs. It exposes twelve focused tools over stdio for clients such as Claude Code and Codex.

The server requires Node.js 20 or newer and a Serper.dev API key. Every request consumes credits from the configured Serper account according to Serper's current pricing.

Tools

MCP tool	Serper endpoint	Purpose	Required parameters
serper_search	search	Google web results	q
serper_images	images	Google image results	q
serper_videos	videos	Google video results	q
serper_places	places	Google local place results	q
serper_maps	maps	Google Maps place results	At least one of q, placeId, or cid
serper_reviews	reviews	Reviews for a Google place	At least one of cid, fid, or placeId
serper_news	news	Google News results	q
serper_shopping	shopping	Google Shopping results	q
serper_lens	lens	Google Lens analysis of an image	url
serper_patents	patents	Google Patents results	q
serper_autocomplete	autocomplete	Google query suggestions	q
serper_scrape	scrape	Extract content from a web page	url

Parameters

Search-like tools accept the following parameters where shown below:

• q (string): query text.
• location (string, optional): geographic location for localized results.
• gl (string, optional): two-letter lowercase country code, such as us or tr.
• hl (string, optional): two-letter lowercase interface language code, such as en or tr.
• tbs (string, optional): Google time-based filter, such as qdr:h or qdr:m.
• num (positive integer, optional): requested maximum result count.
• page (positive integer, optional): one-based result page.

serper_search, serper_images, serper_videos, serper_places, serper_news, serper_shopping, and serper_patents accept all seven search-like parameters. serper_autocomplete accepts q, location, gl, and hl.

Specialized tools use these parameters:

• serper_maps: optional q, hl, ll, placeId, cid, and page. At least one of q, placeId, or cid is required. ll identifies the map center/zoom string accepted by Serper.
• serper_reviews: optional cid, fid, placeId, gl, hl, sortBy, topicId, and nextPageToken. At least one place identifier is required. sortBy is one of mostRelevant, newest, highestRating, or lowestRating.
• serper_lens: required url, plus optional location, gl, hl, and tbs.
• serper_scrape: required url and optional boolean includeMarkdown.

Lens and scrape URLs must use http or https. Each successful call returns the complete Serper object as MCP structuredContent, plus pretty-printed JSON text for clients without structured-output support.

Run with npx

The package is designed to be launched by an MCP client, but it can be started directly when SERPER_API_KEY is already set in the process environment:

SERPER_API_KEY=YOUR_KEY npx -y serper-dev-mcp

The process communicates using MCP JSON-RPC on stdout, so it does not print a startup banner.

Claude Code

Register it for the current user:

claude mcp add --scope user serper-dev -e SERPER_API_KEY=YOUR_KEY -- npx -y serper-dev-mcp

Use --scope project instead of --scope user only when a project-scoped configuration is appropriate. Do not commit a real key in shared MCP configuration.

Codex

Register the server with Codex:

codex mcp add serper-dev --env SERPER_API_KEY=YOUR_KEY -- npx -y serper-dev-mcp

Keep the real value in an environment or secret-management workflow appropriate for your machine rather than in repository files.

Local development

Install and build from source:

git clone https://github.com/GreXLin85/serper.dev-mcp.git
cd serper.dev-mcp
npm install
npm run build
SERPER_API_KEY=YOUR_KEY node dist/index.js

Offline project checks:

npm test
npm run typecheck
npm run build
npm pack --dry-run

The tests inject fake HTTP responses and do not consume Serper credits. For interactive protocol inspection, build the package and launch node dist/index.js through the MCP Inspector, providing SERPER_API_KEY only through its environment configuration.

Security

• The API key is read only from SERPER_API_KEY; it is never a tool argument.
• The server does not log request headers, bodies, successful responses, or the API key.
• HTTP response details are bounded and reflected credentials are redacted before errors cross the MCP boundary.
• Network, timeout, invalid-response, and unexpected errors use safe messages without stack traces.
• Only http and https URLs are accepted by Lens and scrape tools.
• .env files and the local requests reference file are excluded from Git and the npm package.

Revoke and rotate any credential that has been pasted into a command, document, issue, chat, or other non-secret store before publishing or sharing the repository.

Publishing checklist

Before releasing a version:

1. Revoke any previously exposed key and confirm no credential is present in tracked files or Git history.
2. Run npm test, npm run typecheck, and npm run build on Node.js 20 or newer.
3. Run npm pack --dry-run and confirm the package contains only compiled dist output, README.md, LICENSE, and npm-generated package metadata.
4. Inspect the twelve advertised tools with MCP Inspector using a non-production key with limited credits.
5. Update the version and release notes, then publish with the intended npm account and provenance settings.
6. Tag the exact published commit and create the matching GitHub release.

Publishing, remote creation, CI setup, and live API smoke tests are intentionally not automated by this repository.

Credits and license

This project uses the official Model Context Protocol TypeScript SDK and integrates with Serper.dev. It is not affiliated with Google or Serper.dev.

Licensed under the MIT License. Copyright 2026 GreXLin85.