mcp-google-ads

This MCP server provides a bridge between Google Ads data and Claude AI, enabling natural language conversations to access and analyze advertising metrics. Once set up, Claude can request account listings, GAQL queries, and performance metrics through the available tools. The core tools exposed by the server are: list_accounts to enumerate Google Ads accounts, execute_gaql_query to run a GAQL query with your account context, get_campaign_performance to fetch campaign-level metrics over a time range, get_ad_performance for ad-level insights, and run_gaql to execute arbitrary GAQL queries with output formats like table, JSON, or CSV. Authentication is handled via OAuth 2.0 or Service Account credentials, allowing secure access to the Google Ads API and token management. The server processes your requests, fetches data from Google Ads, and returns structured results suitable for visualization and further analysis in Claude or Cursor’s code editor.

Prerequisites:

• Node.js and npm (or access to npm via npx)
• A Google Ads API developer token and proper credentials (OAuth 2.0 client or service account)
• Basic familiarity with GAQL if you plan to build custom queries

Installation steps:

1. Ensure Node.js and npm are installed on your machine. Verify with: node -v npm -v

2. Install or run the MCP server package via npm/npx: npm install -g mcp-google-ads # or use npx -y mcp-google-ads

3. Prepare Google Ads credentials:

   • For OAuth 2.0: obtain client_id, client_secret, and refresh_token
   • For a Service Account: obtain the JSON key file and ensure the account has access to the Google Ads resources

4. Configure environment variables for authentication:

   • GOOGlE_ADS_API_DEVELOPER_TOKEN: your developer token
   • GOGlE_ADS_OAUTH_CLIENT_ID: your OAuth client ID
   • GOGlE_ADS_OAUTH_CLIENT_SECRET: your OAuth client secret
   • GOGlE_ADS_REFRESH_TOKEN: your OAuth refresh token
   • OR GOGlE_ADS_SERVICE_ACCOUNT_KEY: path or contents of the service account key JSON

5. Run the MCP server: npx -y mcp-google-ads

6. Connect Claude or Cursor to the server using the exposed endpoints/tools as described in the README. If running locally, ensure network access to Google Ads API endpoints is allowed.

Tips and common considerations:

• Ensure your Google Ads developer token is approved for the API and that you meet any sandbox/production access requirements.
• If using OAuth, token refreshing is automatic in the server, but you may need to re-authenticate if refresh tokens become invalid.
• When using run_gaql, specify the account_id, the GAQL query, and the desired output format (table, JSON, or CSV).
• For service accounts, grant the service account access to the Google Ads accounts you want to query.
• If you encounter API quota errors, review your developer token quota and request quota increases if needed.
• Keep your credentials secure and do not hard-code sensitive tokens in shared files; use environment variables or secret managers.
• The available tools can be extended; if you add more GAQL-related endpoints, update Claude prompts to reflect new capabilities.