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.)