oauth 2.0 authenticated google ads api access with automatic token refresh
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.
Unique: Implements automatic OAuth token refresh within the MCP server lifecycle using FastMCP decorators, eliminating the need for external token management services or manual credential rotation — the server handles refresh transparently before token expiration during normal operation
vs alternatives: Simpler than building custom OAuth flows because it leverages Google's official authentication libraries and FastMCP's tool registration system, reducing boilerplate and eliminating manual token refresh logic that would otherwise require external schedulers or middleware
multi-account google ads enumeration with account hierarchy discovery
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.
Unique: Exposes account enumeration as a zero-parameter MCP tool that automatically uses the authenticated OAuth context, making account discovery a single-step operation within Claude conversations without requiring users to manually pass credentials or account IDs
vs alternatives: More discoverable than raw Google Ads API because it's wrapped as a named MCP tool with automatic authentication, whereas direct API calls require users to understand OAuth flows and construct API requests manually
google ads query language (gaql) execution with customer and manager account routing
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.
Unique: Wraps GAQL query execution as an MCP tool with automatic OAuth context and manager account routing, allowing Claude to execute complex Google Ads queries conversationally without users manually constructing API requests or managing authentication headers
vs alternatives: More flexible than pre-built reporting tools because it accepts arbitrary GAQL queries, enabling custom analysis patterns; more accessible than raw Google Ads API because authentication and routing are handled automatically within the MCP protocol
keyword research and ideation with performance metrics via google keyword planner integration
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.
Unique: Integrates Google Keyword Planner as an MCP tool with automatic OAuth routing and optional page URL context, enabling keyword research workflows directly within Claude conversations without requiring users to navigate the Google Ads UI or construct API requests
vs alternatives: More integrated than standalone keyword tools because it uses official Google Keyword Planner data and maintains context within the same MCP session; more accessible than raw Google Ads API because parameter handling and result formatting are abstracted
gaql syntax reference and documentation as mcp resource
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.
Unique: Serves GAQL documentation as an MCP resource rather than requiring external web lookups, keeping documentation context within the Claude conversation and enabling inline reference during query construction
vs alternatives: More convenient than external documentation because it's embedded in the MCP session and accessible without context switching; more discoverable than Google's official GAQL docs because it's presented as a named resource within Claude's tool interface
fastmcp framework integration with tool registration and mcp protocol compliance
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.).
Unique: Uses FastMCP's decorator-based tool registration pattern to eliminate manual MCP message handling, allowing developers to define tools as simple Python functions and have the framework handle protocol compliance, serialization, and transport abstraction automatically
vs alternatives: Simpler than manual MCP implementation because decorators abstract protocol details; more flexible than hardcoded tool lists because tools are registered dynamically at runtime and can be extended without modifying core server logic
environment-based configuration with oauth credentials file path management
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.
Unique: Separates OAuth credentials into an external JSON file with path-based configuration, enabling credential rotation and multi-environment deployment without code changes or rebuilding the server
vs alternatives: More secure than hardcoded credentials because credentials are stored separately and can be rotated independently; more flexible than single-credential systems because the OAuth config path can point to different files per environment
claude desktop mcp server registration via claude_desktop_config.json
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.
Unique: Integrates with Claude Desktop's native MCP server discovery mechanism via configuration file, enabling the server to be launched automatically as a subprocess without requiring users to manually start the server or manage process lifecycle
vs alternatives: More user-friendly than manual server startup because Claude Desktop handles process management; more discoverable than HTTP-based MCP servers because tools appear natively in Claude's interface without additional setup