seovimalraj/google-ads-mcp

Google Search MCP Server

A Next.js App Router deployment that exposes a Model Context Protocol (MCP) server focused on organic search research. The server provides three tools—get_autocomplete_suggestions, get_trend_index, and get_keyword_clusters—built on top of Google Suggest, Google Trends, and Search Console. Autocomplete and Trends rely on public endpoints, while clustering authenticates with a Search Console service account.

Features

• Google Autocomplete: Expands up to three seed queries into the real phrases Google users type right now.
• Google Trends: Returns interest-over-time indices for up to three keywords with optional geo and category filters.
• Keyword clustering: Merges Search Console queries and Google Autocomplete expansions into intent-driven groups with page recommendations.
• Next.js 15 App Router with strict TypeScript, ESLint, and Prettier configuration.
• Structured MCP responses with consistent error handling and lightweight rate limiting.

Requirements

• Node.js 18.18 or newer.
• pnpm or npm for dependency management.
• Google Search Console service account credentials (only for get_keyword_clusters).

Getting started locally

pnpm install
pnpm dev

The development server defaults to http://localhost:3000.

Search Console credentials

The keyword clustering tool queries the Google Search Console Search Analytics API using a service account. Set the following environment variables before running the server:

• GOOGLE_CLIENT_EMAIL – service account email with access to the Search Console property.
• GOOGLE_PRIVATE_KEY – private key for the service account (escape newlines as \n in .env).

Alternative variable names (GOOGLE_SERVICE_ACCOUNT_EMAIL, GOOGLE_SERVICE_ACCOUNT_KEY, and GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY) are also recognised for compatibility.

MCP tools

All tools share the same POST endpoint: POST /api/mcp with JSON payload {"tool": "<name>", "input": { ... } }. Responses follow the ToolResponse shape ({ ok: true, data } or { ok: false, error }).

The server also understands the MCP Streamable HTTP JSON-RPC envelope, so agents that negotiate with initialize, tools/list, and tools/call will work without any proxy layer. The legacy JSON format shown below remains supported for quick manual testing.

ping

{
  "tool": "ping"
}

Result:

{
  "ok": true,
  "data": { "status": "ok" }
}

get_autocomplete_suggestions

Fetches live suggestions from Google Suggest. You can continue sending a single query or batch up to three with the queries array.

{
  "tool": "get_autocomplete_suggestions",
  "input": { "queries": ["toroidal transformer", "toroidal core"] }
}

Result:

{
  "ok": true,
  "data": {
    "queries": ["toroidal transformer", "toroidal core"],
    "results": [
      {
        "query": "toroidal transformer",
        "suggestions": [
          "toroidal transformer winding",
          "toroidal transformer core"
        ]
      },
      {
        "query": "toroidal core",
        "suggestions": ["toroidal core material", "toroidal core design"]
      }
    ],
    "combinedSuggestions": [
      "toroidal transformer winding",
      "toroidal transformer core",
      "toroidal core material",
      "toroidal core design"
    ]
  }
}

get_trend_index

Returns Google Trends interest-over-time data. Optional fields (geo, timeRange, category, property) map directly to the underlying Trends API. Provide keyword for backwards compatibility or batch up to three terms with keywords.

{
  "tool": "get_trend_index",
  "input": {
    "keywords": ["toroidal transformer", "toroidal core"],
    "timeRange": "today 12-m",
    "geo": "US"
  }
}

Result (truncated):

{
  "ok": true,
  "data": {
    "keyword": "toroidal transformer",
    "keywords": ["toroidal transformer", "toroidal core"],
    "geo": "US",
    "timeRange": "today 12-m",
    "seriesLabels": ["toroidal transformer", "toroidal core"],
    "averages": [42, 18],
    "points": [
      {
        "time": "1704067200",
        "formattedTime": "Dec 31, 2023",
        "values": [37, 12]
      }
    ]
  }
}

get_keyword_clusters

Produces intent-based keyword clusters by combining Google Search Console performance data with optional Google Autocomplete expansions. Provide a verified siteUrl and an optional seed query. The tool scores clusters, maps them to the best-performing page, and suggests next steps.

{
  "tool": "get_keyword_clusters",
  "input": {
    "query": "solar panels",
    "siteUrl": "https://example.com/",
    "timeRange": "last_90_days",
    "maxKeywords": 1500
  }
}

Result (truncated):

{
  "ok": true,
  "data": {
    "query": "solar panels",
    "siteUrl": "https://example.com/",
    "clusters": [
      {
        "label": "solar panel installation",
        "priority": 78,
        "representativeKeyword": "solar panel installation cost",
        "mappedPage": { "type": "existing", "url": "https://example.com/solar/installation" },
        "rollup": {
          "keywords": 9,
          "sumImpressions": 18400,
          "sumClicks": 1240,
          "avgCtr": 0.045,
          "avgPosition": 6.2
        },
        "recommendations": [
          "Update page for \"solar panel installation\" with FAQs and subtopics.",
          "Add internal links from related pages."
        ]
      }
    ]
  }
}

Advanced Google data sources to explore

Looking to extend the MCP server further? Google exposes several additional surfaces that complement autocomplete and Trends:

• Search Console API: Pull verified site performance data (clicks, impressions, CTR) to validate organic opportunities.
• People Also Ask / Related Searches: Scrape or proxy the SERP modules for question-driven keyword ideation.
• Google Ads Keyword Planner: Estimate paid search volume, bid ranges, and competition scores when you have Ads access.
• Google Discover and News trends: Track emerging stories for content roadmaps using the Discover feed and Google News APIs.
• Google Analytics Data API: Blend on-site engagement metrics with keyword demand to prioritise high-impact opportunities.

Rate limiting & errors

• Rate limiting: 10 requests per minute per IP/user agent combination. Exceeding the budget returns 429 with code: RATE_LIMIT_EXCEEDED.
• Upstream issues: Failures from Google endpoints map to UPSTREAM_ERROR with the HTTP status and service name.
• Validation errors: Invalid input payloads return INVALID_ARGUMENT and include Zod field errors.
• Unexpected failures: Return 500 with code: UNKNOWN but never leak secrets.

ChatGPT Developer Mode integration

Add a remote MCP server in ChatGPT using the following configuration:

• Server URL: https://<your-app>.vercel.app/api/mcp
• Tools: Automatically discovered (ping, get_autocomplete_suggestions, get_trend_index, get_keyword_clusters).
• Auth flow: None required—both tools rely on public Google endpoints.

Example invocation in ChatGPT:

{
  "tool": "get_trend_index",
  "input": { "keyword": "toroidal transformer" }
}

Expect a JSON payload with interest-over-time points that you can combine with autocomplete suggestions or the get_keyword_clusters tool to validate seasonal demand and prioritise content.

Troubleshooting

Acceptance checklist

• Autocomplete MCP tool returning Google Suggest phrases.
• Trends MCP tool returning interest-over-time data.
• Keyword clustering MCP tool grouping Search Console queries into recommendations.
• README covering setup, usage, and troubleshooting.