Google Ads

Implements a transparent OAuth 2.0 authentication layer that handles the complete Google authentication flow, including token acquisition, automatic refresh, and credential management without requiring manual intervention from users. The system stores OAuth credentials in a JSON configuration file and automatically refreshes tokens before expiration, eliminating the need for users to manually re-authenticate or manage API keys. Built on Google's authentication libraries with integration into the FastMCP framework for seamless MCP protocol compliance.

Provides a tool that lists all accessible Google Ads accounts associated with the authenticated user, enabling discovery of account hierarchies and manager accounts. The list_accounts tool queries the Google Ads API to return account metadata including customer IDs, account names, and account types, allowing users to identify which accounts they have access to before executing operations. This capability integrates directly with the OAuth authentication system to ensure only authorized accounts are returned.

Implements a run_gaql tool that executes arbitrary Google Ads Query Language queries against specified customer accounts, with support for both direct customer accounts and manager account queries. The tool accepts a GAQL query string, customer_id, and optional manager_id parameter, then routes the query to the appropriate Google Ads API endpoint with automatic OAuth authentication. Results are returned as structured JSON, enabling programmatic analysis of campaign performance, keyword metrics, ad group data, and other Google Ads entities.

Provides a run_keyword_planner tool that generates keyword ideas and associated metrics (search volume, competition level, bid estimates) using Google's Keyword Planner API. The tool accepts a list of seed keywords, target customer account, optional page URL for context, and optional manager_id, then returns structured keyword data with performance metrics. This enables keyword research workflows within Claude conversations, allowing users to discover new keywords and understand their competitive landscape without leaving the MCP interface.

Exposes a gaql_reference resource containing complete GAQL syntax documentation, field references, and query examples that Claude can access during conversations. This resource is served as part of the MCP protocol, allowing Claude to retrieve GAQL documentation without external web lookups. The reference includes supported entities (Campaign, AdGroup, Keyword, etc.), available fields, filtering operators, and example queries, enabling users to construct valid GAQL queries with inline documentation.

Implements the core MCP server using FastMCP framework, which provides automatic tool registration via Python decorators, MCP protocol message handling, and transport abstraction (STDIO and HTTP modes). The server.py file uses FastMCP decorators (@mcp.tool, @mcp.resource) to register the list_accounts, run_gaql, and run_keyword_planner tools, and the framework handles serialization, error handling, and protocol compliance automatically. This architecture eliminates manual MCP message construction and enables the server to work with any MCP-compatible client (Claude Desktop, custom agents, etc.).

Implements configuration management via environment variables (.env file) and external OAuth credentials JSON file, allowing users to configure the server without modifying source code. The system reads GOOGLE_ADS_DEVELOPER_TOKEN and GOOGLE_ADS_OAUTH_CONFIG_PATH from environment variables, then loads the OAuth credentials from the specified JSON file path. This pattern enables secure credential storage, easy deployment across environments, and credential rotation without code changes.

Provides integration with Claude Desktop through the claude_desktop_config.json configuration file, which specifies the Python executable path and server.py location. This configuration file enables Claude Desktop to discover and launch the MCP server automatically, establishing the connection between Claude's conversational interface and the Google Ads tools. The server runs as a subprocess managed by Claude Desktop, with communication via STDIO protocol.