serpapi-mcp

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