@channel47/google-ads-mcp 1.0.7 → 1.1.0

package/README.md

@@ -3,22 +3,25 @@
 [![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).
+MCP server for Google Ads API access via GAQL (Google Ads Query Language). Built by a practitioner managing 25+ ad accounts daily — not a demo.
 
-## Overview
+Part of [Channel 47](https://channel47.dev), the open-source ecosystem of profession plugins for Claude Code. [Get the newsletter](https://channel47.dev/subscribe) for weekly skill breakdowns from production use.
 
-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.
+## What It Does
+
+- **List accounts** accessible under your MCC or individual credentials
+- **Query anything** with raw GAQL — campaigns, ad groups, keywords, search terms, assets, any resource
+- **Mutate entities** — campaigns, ad groups, ads, keywords, budgets, assets with dry-run safety
+- **Resources and prompts** — bundled GAQL reference docs and operation templates
 
 ## 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!
+Bundled with the [media-buyer plugin](https://github.com/channel47/channel47). No manual install required.
 
 ### Standalone Use
 
-For use with other MCP clients or standalone testing:
-
 ```bash
 npx @channel47/google-ads-mcp@latest
 ```
@@ -32,8 +35,6 @@ google-ads-mcp
 
 ## Configuration
 
-Set these environment variables before running:
-
 ### Required
 
 | Variable | Description |
@@ -231,91 +232,28 @@ Campaign creation requires specific fields since Google Ads API v19.2 (September
 - `target_impression_share` - Target impression share
 - `bidding_strategy` - Reference to portfolio bidding strategy
 
-## 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
+git clone https://github.com/channel47/mcps.git
+cd mcps
+npm install    # workspaces — installs all servers
+npm test       # runs all server tests
 ```
 
-## Architecture
+~200 lines of server code. 3 core tools. Dry-run by default. OAuth 2.0 with environment-based credentials.
 
-**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
+Pairs with the [media-buyer plugin](https://github.com/channel47/channel47), which adds skills, mutation validation hooks, and GAQL reference docs on top of this server.
 
 ## Links
 
+- [Channel 47](https://channel47.dev) — open-source profession plugins for Claude Code
+- [Build Notes](https://channel47.dev/subscribe) — weekly skill breakdowns from production use
+- [Media Buyer Plugin](https://github.com/channel47/channel47) — the paid-search toolkit this MCP powers
 - [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)
+- [Google Ads API](https://developers.google.com/google-ads/api/docs/start) / [GAQL Reference](https://developers.google.com/google-ads/api/docs/query/overview)
+- [X](https://x.com/ctrlswing) / [LinkedIn](https://www.linkedin.com/in/jackson-d-9979a7a0/) / [GitHub](https://github.com/channel47)
 
 ## 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)
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@channel47/google-ads-mcp",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "description": "Google Ads MCP Server - Query and mutate Google Ads data using GAQL",
   "main": "server/index.js",
   "bin": {
@@ -31,12 +31,13 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/channel47/google-ads-mcp-server.git"
+    "url": "https://github.com/channel47/mcps.git",
+    "directory": "google-ads"
   },
   "bugs": {
-    "url": "https://github.com/channel47/google-ads-mcp-server/issues"
+    "url": "https://github.com/channel47/mcps/issues"
   },
-  "homepage": "https://github.com/channel47/google-ads-mcp-server#readme",
+  "homepage": "https://github.com/channel47/mcps/tree/main/google-ads#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "google-ads-api": "^21.0.1",

package/server/index.js

@@ -50,8 +50,11 @@ const server = new Server(
   }
 );
 
+// Read-only mode: set GOOGLE_ADS_READ_ONLY=true to disable mutate tool
+const READ_ONLY = process.env.GOOGLE_ADS_READ_ONLY === 'true';
+
 // Tool definitions
-const TOOLS = [
+const ALL_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.',
@@ -143,6 +146,12 @@ For IMAGE/VIDEO assets, use 'image_file_path' or 'video_file_path' with absolute
   }
 ];
 
+const TOOLS = READ_ONLY ? ALL_TOOLS.filter(t => t.name !== 'mutate') : ALL_TOOLS;
+
+if (READ_ONLY) {
+  console.error('Read-only mode enabled — mutate tool disabled');
+}
+
 // Register list_tools handler
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   return { tools: TOOLS };
@@ -161,6 +170,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return await runGaqlQuery(params);
 
       case 'mutate':
+        if (READ_ONLY) throw new Error('Mutate is disabled in read-only mode (GOOGLE_ADS_READ_ONLY=true)');
         return await mutate(params);
 
       default: