@channel47/google-ads-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Channel47
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# @channel47/google-ads-mcp
+
+[![npm version](https://badge.fury.io/js/@channel47%2Fgoogle-ads-mcp.svg)](https://www.npmjs.com/package/@channel47/google-ads-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+MCP server for Google Ads API access via GAQL (Google Ads Query Language).
+
+## Overview
+
+This is a Model Context Protocol (MCP) server that provides tools for querying and mutating Google Ads data using GAQL. It's designed to work seamlessly with Claude Code and other MCP-compatible clients.
+
+## Installation
+
+### For Claude Code Plugin Users
+
+This package is automatically installed when using the [google-ads-specialist Claude Code plugin](https://marketplace.claude.com/plugins/google-ads-specialist). No manual installation required!
+
+### Standalone Use
+
+For use with other MCP clients or standalone testing:
+
+```bash
+npx @channel47/google-ads-mcp@latest
+```
+
+Or install globally:
+
+```bash
+npm install -g @channel47/google-ads-mcp
+google-ads-mcp
+```
+
+## Configuration
+
+Set these environment variables before running:
+
+### Required
+
+| Variable | Description |
+|----------|-------------|
+| `GOOGLE_ADS_DEVELOPER_TOKEN` | Your Google Ads API Developer Token |
+| `GOOGLE_ADS_CLIENT_ID` | OAuth 2.0 Client ID from Google Cloud |
+| `GOOGLE_ADS_CLIENT_SECRET` | OAuth 2.0 Client Secret |
+| `GOOGLE_ADS_REFRESH_TOKEN` | OAuth 2.0 Refresh Token |
+
+### Optional
+
+| Variable | Description |
+|----------|-------------|
+| `GOOGLE_ADS_LOGIN_CUSTOMER_ID` | MCC Account ID (10 digits, no dashes) |
+| `GOOGLE_ADS_DEFAULT_CUSTOMER_ID` | Default account ID for queries |
+
+## Tools
+
+### list_accounts
+
+List all accessible Google Ads accounts.
+
+**Returns:** Array of account objects with ID, name, currency, and status.
+
+### query
+
+Execute any GAQL SELECT query. Returns clean JSON results.
+
+**Parameters:**
+- `customer_id` (string, optional): Account ID (10 digits, no dashes)
+- `query` (string, required): GAQL SELECT query
+- `limit` (integer, optional): Max rows to return (default: 100, max: 10000)
+
+**Example:**
+```javascript
+{
+  "customer_id": "1234567890",
+  "query": "SELECT campaign.name, campaign.status FROM campaign WHERE campaign.status = 'ENABLED'",
+  "limit": 50
+}
+```
+
+### mutate
+
+Execute write operations using GoogleAdsService.Mutate.
+
+**Parameters:**
+- `customer_id` (string, optional): Account ID
+- `operations` (array, required): Mutation operations
+- `partial_failure` (boolean, optional): Enable partial failure mode (default: true)
+- `dry_run` (boolean, optional): Validate without executing (default: true for safety)
+
+**Example:**
+```javascript
+{
+  "customer_id": "1234567890",
+  "operations": [
+    {
+      "campaignOperation": {
+        "update": {
+          "resourceName": "customers/1234567890/campaigns/123",
+          "status": "PAUSED"
+        },
+        "updateMask": "status"
+      }
+    }
+  ],
+  "dry_run": false
+}
+```
+
+## Resources & Prompts
+
+The server provides:
+- **Resources**: GAQL reference documentation accessible via MCP resources
+- **Prompts**: Templates for common Google Ads operations
+
+## Usage with Claude Code
+
+This server is designed to work with the [google-ads-specialist plugin](https://marketplace.claude.com/plugins/google-ads-specialist), which provides:
+
+- **9 Skill Files**: Progressive disclosure of GAQL patterns and best practices
+  - Atomic skills for focused tasks (campaign performance, search terms, wasted spend, etc.)
+  - Playbooks for comprehensive workflows (account health audit)
+  - Troubleshooting guides for common errors
+- **PreToolUse Hook**: Validates skill references before query/mutate operations
+- **Comprehensive Documentation**: Setup guides and OAuth configuration help
+
+The plugin ensures Claude consults domain knowledge before executing queries, preventing hallucinated GAQL.
+
+## Development
+
+### Prerequisites
+
+- Node.js 18 or higher
+- Google Ads API access (Developer Token)
+- OAuth 2.0 credentials from Google Cloud
+
+### Setup
+
+```bash
+git clone https://github.com/channel47/google-ads-mcp-server.git
+cd google-ads-mcp-server
+npm install
+```
+
+### Testing
+
+```bash
+npm test
+```
+
+### Running Locally
+
+```bash
+npm start
+```
+
+## Architecture
+
+**Minimal Design:**
+- ~200 lines of server code
+- 3 core tools (list, query, mutate)
+- OAuth 2.0 authentication
+- Resources for GAQL reference
+- Prompts for common patterns
+
+**Security:**
+- Dry-run mode enabled by default for mutations
+- Environment-based credential management
+- Input validation for all operations
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes with tests
+4. Submit a pull request
+
+## Links
+
+- [NPM Package](https://www.npmjs.com/package/@channel47/google-ads-mcp)
+- [GitHub Repository](https://github.com/channel47/google-ads-mcp-server)
+- [Claude Code Plugin](https://marketplace.claude.com/plugins/google-ads-specialist)
+- [Google Ads API Documentation](https://developers.google.com/google-ads/api/docs/start)
+- [GAQL Reference](https://developers.google.com/google-ads/api/docs/query/overview)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+
+## License
+
+MIT - See [LICENSE](LICENSE) file for details.
+
+## Support
+
+For issues or questions:
+- Plugin-related: [Plugin Repository Issues](https://github.com/ctrlswing/channel47-marketplace/issues)
+- Server-related: [Server Repository Issues](https://github.com/channel47/google-ads-mcp-server/issues)

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@channel47/google-ads-mcp",
+  "version": "1.0.0",
+  "description": "Google Ads MCP Server - Query and mutate Google Ads data using GAQL",
+  "main": "server/index.js",
+  "bin": {
+    "google-ads-mcp": "server/index.js"
+  },
+  "type": "module",
+  "files": [
+    "server/**/*.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node server/index.js",
+    "test": "node --test *.test.js test/*.test.js",
+    "lint": "eslint server/",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "google-ads",
+    "gaql",
+    "analytics",
+    "advertising",
+    "claude"
+  ],
+  "author": "Channel47",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/channel47/google-ads-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/channel47/google-ads-mcp-server/issues"
+  },
+  "homepage": "https://github.com/channel47/google-ads-mcp-server#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "google-ads-api": "^21.0.1",
+    "google-auth-library": "^9.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/server/auth.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { GoogleAdsApi } from 'google-ads-api';
+
+// Required environment variables for OAuth 2.0 authentication
+const REQUIRED_ENV_VARS = [
+  'GOOGLE_ADS_DEVELOPER_TOKEN',
+  'GOOGLE_ADS_CLIENT_ID',
+  'GOOGLE_ADS_CLIENT_SECRET',
+  'GOOGLE_ADS_REFRESH_TOKEN',
+];
+
+/**
+ * Validate all required environment variables are present
+ * @returns {{ valid: boolean, missing: string[] }}
+ */
+export function validateEnvironment() {
+  const missing = REQUIRED_ENV_VARS.filter(varName => !process.env[varName]);
+
+  return {
+    valid: missing.length === 0,
+    missing
+  };
+}
+
+let cachedClient = null;
+
+/**
+ * Initialize and return Google Ads API client
+ * Caches client instance for reuse
+ * @returns {GoogleAdsApi}
+ * @throws {Error} If environment variables are missing or invalid
+ */
+export function initializeGoogleAdsClient() {
+  if (cachedClient) {
+    return cachedClient;
+  }
+
+  // Validate environment first
+  const { valid, missing } = validateEnvironment();
+  if (!valid) {
+    throw new Error(
+      `Missing required environment variables: ${missing.join(', ')}\n` +
+      `Please set these variables before starting the server.`
+    );
+  }
+
+  // Initialize Google Ads client
+  try {
+    cachedClient = new GoogleAdsApi({
+      client_id: process.env.GOOGLE_ADS_CLIENT_ID,
+      client_secret: process.env.GOOGLE_ADS_CLIENT_SECRET,
+      developer_token: process.env.GOOGLE_ADS_DEVELOPER_TOKEN,
+    });
+
+    return cachedClient;
+  } catch (error) {
+    throw new Error(`Failed to initialize Google Ads client: ${error.message}`);
+  }
+}
+
+/**
+ * Get authenticated customer client for a specific account
+ * @param {string} customerId - Google Ads account ID (without dashes)
+ * @returns {Customer}
+ */
+export function getCustomerClient(customerId) {
+  const client = initializeGoogleAdsClient();
+
+  return client.Customer({
+    customer_id: customerId,
+    refresh_token: process.env.GOOGLE_ADS_REFRESH_TOKEN,
+    login_customer_id: process.env.GOOGLE_ADS_LOGIN_CUSTOMER_ID,
+  });
+}

package/server/index.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+// Import auth for validation
+import { validateEnvironment } from './auth.js';
+
+// Import tools
+import { listAccounts } from './tools/list-accounts.js';
+import { runGaqlQuery } from './tools/gaql-query.js';
+import { mutate } from './tools/mutate.js';
+
+// Import resources
+import { getResourcesList, readResource } from './resources/index.js';
+
+// Import prompts
+import { getPromptsList, renderPrompt } from './prompts/templates.js';
+
+// Server metadata
+const SERVER_NAME = 'google-ads-mcp';
+const SERVER_VERSION = '1.0.0';
+
+// Validate environment on startup
+const { valid, missing } = validateEnvironment();
+if (!valid) {
+  console.error(`Missing required environment variables: ${missing.join(', ')}`);
+  process.exit(1);
+}
+
+// Create MCP server
+const server = new Server(
+  {
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+  },
+  {
+    capabilities: {
+      tools: {},
+      prompts: {},
+      resources: {},
+    },
+  }
+);
+
+// Tool definitions
+const TOOLS = [
+  {
+    name: 'list_accounts',
+    description: 'List all accessible Google Ads accounts under the authenticated user or MCC. Use this first to find account IDs before running other tools.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        include_manager_accounts: {
+          type: 'boolean',
+          description: 'Include manager (MCC) accounts in results',
+          default: false
+        }
+      }
+    }
+  },
+  {
+    name: 'query',
+    description: 'Execute any GAQL SELECT query. Returns clean JSON results. Mutations are blocked - use mutate tool for write operations.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        customer_id: {
+          type: 'string',
+          description: 'Google Ads account ID (optional, uses default if not specified)'
+        },
+        query: {
+          type: 'string',
+          description: 'Full GAQL query string (SELECT only)'
+        },
+        limit: {
+          type: 'integer',
+          description: 'Maximum rows to return (default: 100, max: 10000)',
+          default: 100
+        }
+      },
+      required: ['query']
+    }
+  },
+  {
+    name: 'mutate',
+    description: 'Execute write operations using GoogleAdsService.Mutate. Supports all operation types. Default dry_run=true for safety.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        customer_id: {
+          type: 'string',
+          description: 'Google Ads customer ID (optional, uses default if not specified)'
+        },
+        operations: {
+          type: 'array',
+          description: 'Array of mutation operation objects',
+          items: {
+            type: 'object'
+          }
+        },
+        partial_failure: {
+          type: 'boolean',
+          description: 'Enable partial failure mode (default: true)',
+          default: true
+        },
+        dry_run: {
+          type: 'boolean',
+          description: 'Validate only, do not execute (default: true)',
+          default: true
+        }
+      },
+      required: ['operations']
+    }
+  }
+];
+
+// Register list_tools handler
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools: TOOLS };
+});
+
+// Register call_tool handler
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: params } = request.params;
+
+  try {
+    switch (name) {
+      case 'list_accounts':
+        return await listAccounts(params);
+
+      case 'query':
+        return await runGaqlQuery(params);
+
+      case 'mutate':
+        return await mutate(params);
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    console.error(`Tool error (${name}):`, error);
+    throw error;
+  }
+});
+
+// Register list_prompts handler
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+  return { prompts: getPromptsList() };
+});
+
+// Register get_prompt handler
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    return renderPrompt(name, args || {});
+  } catch (error) {
+    console.error(`Prompt error (${name}):`, error);
+    throw error;
+  }
+});
+
+// Register list_resources handler
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  return { resources: getResourcesList() };
+});
+
+// Register read_resource handler
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params;
+
+  try {
+    return readResource(uri);
+  } catch (error) {
+    console.error(`Resource error (${uri}):`, error);
+    throw error;
+  }
+});
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  console.error(`${SERVER_NAME} v${SERVER_VERSION} started`);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});