serpapi-mcp

A wrapper skill that calls SerpAPI’s MCP server (Model Context Protocol) via the mcporter CLI.

What this skill provides

• Runs SerpAPI searches from OpenClaw via MCP (HTTP).
• Returns the full SerpAPI JSON to stdout (the primary contract).
• Optionally persists each query + response into Airtable:
• raw JSON (full SerpAPI payload)
• a structured “summary” (Top 10 organics, PAA/Related questions, videos, images, counts, flags)

/serp usage

Treat this skill as providing the /serp command.

Syntax: - /serp <query> - /serp <query> [engine] [num] [mode]

Defaults: - engine=google_light - num=5 - mode=compact

Notes: - If you want SERP features such as People also ask (PAA), video packs, knowledge graph, etc., prefer: - engine=google - mode=complete

Examples: - /serp site:cnmv.es "educación financiera" - /serp "AAPL stock" google 3 compact - /serp "mortgage pay off vs invest" google 10 complete

How it works

Main script (prints JSON to stdout): - skills/serpapi-mcp/scripts/serp.sh "<query>" [engine] [num] [mode]

It calls this MCP tool endpoint: - https://mcp.serpapi.com/$SERPAPI_API_KEY/mcp.search

Optional Airtable logger: - skills/serpapi-mcp/scripts/airtable_log.mjs

Requirements

1) MCP client (mcporter)

This skill requires mcporter installed on the host.

Install: - npm install -g mcporter

Verify: - mcporter --help

2) SerpAPI key(s) + failover

You can configure either a single key or a failover pool:

• Single key:
• SERPAPI_API_KEY
• Failover pool (comma-separated, tried in order):
• SERPAPI_API_KEYS

Recommended placement (any of these is supported): - Skill-scoped: - skills.entries.serpapi-mcp.env.SERPAPI_API_KEY - skills.entries.serpapi-mcp.env.SERPAPI_API_KEYS - Global: - env.vars.SERPAPI_API_KEY - env.vars.SERPAPI_API_KEYS

Failover behavior: - The script retries with the next key on common quota / auth / rate-limit errors (e.g. 429/401/403, “quota exceeded”, “rate limit”). - For other errors (e.g. malformed request), it stops early and returns the error.

Optional: store searches/results in Airtable

Enable / disable

Enable logging: - SERP_LOG_AIRTABLE=1 (or true)

You can set this globally in the Gateway env (always on) or per-run when executing the script.

Airtable configuration (Gateway env)

Set these environment variables (do not store secrets in the repo/workspace): - AIRTABLE_TOKEN (Airtable Personal Access Token) - AIRTABLE_BASE_ID - AIRTABLE_TABLE (table name or table id)

Write behavior & compatibility

• Airtable does not auto-create fields.
• The logger is schema-aware:
• It reads the table schema via Airtable Metadata API.
• It only writes fields that already exist in your table (by name).
• It coerces values to the Airtable field type when possible (checkbox/number/text/select/date).

Airtable table schema (recommended)

Field names must match exactly.

Core: - Query → Single line text - Engine → Single line text - Num → Number (integer) - Mode → Single line text - CreatedAt → Date/Time

Provenance: - SerpApiSearchId → Single line text - SerpApiJsonEndpoint → URL - GoogleUrl → URL

Raw payload: - ResultJson → Long text - ResultJsonTruncatedFlag → Checkbox - (Back-compat: the logger also supports ResultJsonTruncated if you prefer that name.)

Structured summary: - SummaryJson → Long text - SummaryJsonTruncated → Checkbox - OrganicTop10Json → Long text - RelatedQuestionsTop10Json → Long text - ShortVideosTop10Json → Long text - VideosTop10Json → Long text - ImagesTop10Json → Long text

Flags + counts: - HasAiOverview → Checkbox - HasAnswerBox → Checkbox - HasKnowledgeGraph → Checkbox - OrganicCount → Number (integer) - RelatedQuestionsCount → Number (integer) - ShortVideosCount → Number (integer) - VideosCount → Number (integer) - ImagesCount → Number (integer)

Airtable size limits

Airtable has per-cell size limits. The logger truncates JSON strings if needed: - AIRTABLE_MAX_JSON_CHARS (default: 90000) - AIRTABLE_MAX_SUMMARY_CHARS (default: 90000)

Output

Returns SerpAPI JSON. Depending on engine and what Google shows, the payload may include keys like: - organic_results - short_videos / videos_results - images_results - related_questions - knowledge_graph - answer_box / ai_overview - ads blocks (top_ads, bottom_ads, etc.)