Google Ads MCP Server

A Next.js App Router deployment that exposes a Model Context Protocol (MCP) server backed by the Google Ads Keyword Planner. The server provides three tools—get_keyword_ideas, get_historical_metrics, and get_forecast—with secure OAuth, encrypted credential storage, in-flight validation, and lightweight rate limiting. It is optimised for Vercel (Node.js runtime) but runs locally with the same feature set.

Features

• Next.js 15 App Router using strict TypeScript, ESLint, and Prettier.

• MCP tools for keyword discovery, historical metrics, and forecasts.

• Google OAuth 2.0 flow with AES-256-GCM encrypted refresh token storage.

• KV persistence via Vercel KV with an automatic in-memory fallback for local development.

• Zod validation for every tool input plus environment assertions.

• Token bucket rate limiting (10 requests/minute per user/IP).

• Structured logging & error mapping for predictable MCP responses.

Requirements

• Node.js 18.18 or newer (Next.js 15 canary requires ≥18.18).

• pnpm or npm for dependency management.

• A Google Ads Manager account with API access.

• Google Cloud OAuth client (type: Web application) authorised for the deployment URL.

• Vercel KV database (or compatible Upstash REST endpoint).

Environment variables

Create a .env file (or configure Vercel project secrets) that includes all variables from .env.example.

ℹ️ If any required variable is missing the server throws an explicit error at startup, ensuring you see actionable messages in local development and on Vercel logs.

Project structure

Getting started locally

The development server defaults to http://localhost:3000. Ensure your Google OAuth client has that origin and callback (http://localhost:3000/api/auth/callback) added to the authorised redirect URIs.

Running without Vercel KV

If KV_REST_API_URL or KV_REST_API_TOKEN is missing the server logs a warning and stores tokens in-memory. This is ideal for local testing but not for production because refresh tokens will be lost on redeploys.

OAuth flow

1. Direct the browser (or an HTTP client) to /api/auth/start?userId=<USER>&customerId=<CUSTOMER_ID>.

2. Google prompts for consent with the https://www.googleapis.com/auth/adwords scope.

3. On success Google redirects to /api/auth/callback. The server exchanges the code for tokens, encrypts the refresh token with AES-256-GCM, and persists it in KV.

4. The callback endpoint renders a simple confirmation page. Tokens are now available to all MCP tools via the stored userId.

The state parameter is encrypted to prevent tampering and includes the user/customer IDs plus a timestamp.

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

ping

Result:

get_keyword_ideas

get_historical_metrics

get_forecast

All tool inputs are validated by Zod. Errors return HTTP 400 and a structured payload:

Rate limiting & errors

• Rate limiting: 10 requests per minute per user (falls back to IP if userId missing). Exceeding the budget returns 429 with code: RATE_LIMIT_EXCEEDED.

• Authentication errors: Missing or corrupt refresh tokens map to AUTHENTICATION_ERROR (HTTP 401).

• Permission issues: Google Ads permission denials map to PERMISSION_DENIED (HTTP 403).

• Quota problems: API quota issues map to QUOTA_EXCEEDED (HTTP 429).

• Unexpected failures: Return 500 with code: UNKNOWN but never leak secrets.

Structured logs (via console.log / console.error) include tool name, user ID, duration, and error codes to help diagnose incidents quickly.

Deployment on Vercel

1. Push the repository to GitHub and create a Vercel project targeting this repo.

2. Set the production environment variables listed above. Remember to generate a strong ENCRYPTION_KEY and configure KV credentials.

3. Deploy. Vercel automatically builds the Next.js app in the Node.js runtime.

4. After deployment, run the OAuth flow (https://<app>.vercel.app/api/auth/start?...) and confirm the callback stores the token (check logs or /api/mcp ping).

5. Smoke test each tool with curl or the MCP client using the production URL.

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_keyword_ideas, get_historical_metrics, get_forecast).

• Auth flow: Run /api/auth/start in a browser before invoking any tool so the refresh token is available.

Example invocation in ChatGPT (after auth):

Expect a JSON array of keyword ideas with text, competition, and bid ranges.

Troubleshooting

Acceptance checklist

• App Router structure with TypeScript, ESLint, Prettier, and strict mode.

• OAuth start/callback routes using AES-256-GCM encrypted refresh tokens.

• KV abstraction with Vercel + in-memory modes.

• Google Ads helpers for keyword ideas, historical metrics, and forecasts.

• MCP tools with validation, rate limiting, and error handling.

• README covering setup, usage, deployment, and troubleshooting.