{"_id":"@adginr/google-ads-mcp","_rev":"5-811809d7135fa73156c911a9201a3d26","name":"@adginr/google-ads-mcp","dist-tags":{"latest":"0.4.0"},"versions":{"0.0.0-stage":{"name":"@adginr/google-ads-mcp","version":"0.0.0-stage","_id":"@adginr/google-ads-mcp@0.0.0-stage","stub":true,"maintainers":[{"name":"adginr","email":"nickolai.zt@gmail.com"}],"dist":{"shasum":"3ae92ec222726d1efa24b9fc8ccdbaf714e6b282","tarball":"https://registry.npmjs.org/@adginr/google-ads-mcp/-/google-ads-mcp-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-SbR9sOPqnPJ4lG08gFjcVvvtJiUhO97TJrJEDH3LKME8oWVAYjpxSginWhwHQPW17gyWS1Wxvi+cRS1YXn23jA==","signatures":[{"sig":"MEUCIQC2TZIYIoZ6ry0n1ls+lzhXWiJ0r2y+faX5T3iwHV6cfQIgY6Fqb3ZP+bBPJPP7+Djb3DqIJupCGLLqW9AW4G2yDl4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":344},"_npmUser":{"name":"adginr","email":"nickolai.zt@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"0.1.0":{"name":"@adginr/google-ads-mcp","version":"0.1.0","keywords":["google-ads","google-ads-api","mcp","model-context-protocol","mcp-server","claude","ai-agent"],"author":"Kolin (https://adginr.com)","license":"Apache-2.0","_id":"@adginr/google-ads-mcp@0.1.0","maintainers":[{"name":"adginr","email":"nickolai.zt@gmail.com"}],"homepage":"https://github.com/adginr/google-ads-rest/tree/main/packages/mcp#readme","bugs":"https://github.com/adginr/google-ads-rest/issues","bin":{"google-ads-mcp":"./dist/cli.js"},"dist":{"shasum":"028d00a54f6d90a493ad04eb165e3df9c99b2b31","tarball":"https://registry.npmjs.org/@adginr/google-ads-mcp/-/google-ads-mcp-0.1.0.tgz","fileCount":14,"integrity":"sha512-z16qh6mEwkFApzAqHa4eYrPb78skhNQRoAXjwEPN72u9QVUS5AdtSHmtw2eRJF2hWNWLtMDOYbfKY12dc9V68Q==","signatures":[{"sig":"MEUCIQCmQk43HtCQefX2U14hPqY8NDKraNx1gTD8lhLfLRZpHAIgP5Rji9CRVdQbWARiiAwKQGewHIUvOhgtTEjPE5iKF30=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQCKi7lxalM4crDe0jj/tkbbMCL8bqElgBScHdZeEfqMeQIhALuSu3eoSTR5plJifHtMfXYP9PsQkZORLRC2KhB6lEkl","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":35125},"type":"module","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./package.json":"./package.json"},"scripts":{"build":"tsdown","start":"node src/cli.ts","typecheck":"tsc --noEmit","check:package":"publint --strict"},"_npmUser":{"name":"adginr","email":"nickolai.zt@gmail.com"},"repository":{"url":"git+https://github.com/adginr/google-ads-rest.git","type":"git","directory":"packages/mcp"},"description":"Model Context Protocol server for the Google Ads API over REST: GAQL search, keywords, ads, assets, budgets.","directories":{},"_nodeVersion":"24.21.0","dependencies":{"zod":"^4.6.7","@adginr/google-ads-rest":"^0.1.0","@modelcontextprotocol/node":"^2.1.1","@modelcontextprotocol/server":"^2.3.1"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/google-ads-mcp_0.1.0_1792084582581_0.8266418271623026","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@adginr/google-ads-mcp","version":"0.2.0","keywords":["google-ads","google-ads-api","mcp","model-context-protocol","mcp-server","claude","ai-agent"],"author":"Kolin (https://adginr.com)","license":"Apache-2.0","_id":"@adginr/google-ads-mcp@0.2.0","maintainers":[{"name":"adginr","email":"nickolai.zt@gmail.com"}],"homepage":"https://github.com/adginr/google-ads-rest/tree/main/packages/mcp#readme","bugs":"https://github.com/adginr/google-ads-rest/issues","bin":{"google-ads-mcp":"./dist/cli.js"},"dist":{"shasum":"c13e645e9596796de99418fd4aa8a311348b4681","tarball":"https://registry.npmjs.org/@adginr/google-ads-mcp/-/google-ads-mcp-0.2.0.tgz","fileCount":14,"integrity":"sha512-u9cC0ulzPo0LJcXCwmVBljg6GyJFACKkzn7fmoZwjppNH73HVMnyjgBBDQngPr0QUtbfMpCkqQ3d4ZNGWqMpww==","signatures":[{"sig":"MEYCIQDJQG0e5oJwMteEl+9QUHRwjp2DzECuXPuLcx+YclTcygIhAJVuQAqCqWEyACXnOwbp5r+3MFDbfvKo/SalVAW9JZNV","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQCAFuW+gFuX8EHnk0bWvcVS1/rrd4+KgE9Gy7iJhAl6XQIhAJnB9VczypRLX9dfg+KWVdpf8tJE0ZhOjkM6X5YW5PCR","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@adginr%2fgoogle-ads-mcp@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":35257},"type":"module","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./package.json":"./package.json"},"scripts":{"build":"tsdown","start":"node src/cli.ts","typecheck":"tsc --noEmit","check:package":"publint --strict"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"61bc1d6b-8059-4c56-9a3c-a96dd2089b59"}},"repository":{"url":"git+https://github.com/adginr/google-ads-rest.git","type":"git","directory":"packages/mcp"},"description":"Model Context Protocol server for the Google Ads API over REST: GAQL search, keywords, ads, assets, budgets.","directories":{},"_nodeVersion":"24.21.0","dependencies":{"zod":"^4.6.7","@adginr/google-ads-rest":"^0.2.0","@modelcontextprotocol/node":"^2.1.1","@modelcontextprotocol/server":"^2.3.1"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/google-ads-mcp_0.2.0_1792154158818_0.2536945074236352","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@adginr/google-ads-mcp","version":"0.3.0","keywords":["google-ads","google-ads-api","mcp","model-context-protocol","mcp-server","claude","ai-agent"],"author":"Kolin (https://adginr.com)","license":"Apache-2.0","_id":"@adginr/google-ads-mcp@0.3.0","maintainers":[{"name":"adginr","email":"nickolai.zt@gmail.com"}],"homepage":"https://github.com/adginr/google-ads-rest/tree/main/packages/mcp#readme","bugs":"https://github.com/adginr/google-ads-rest/issues","bin":{"google-ads-mcp":"./dist/cli.js"},"dist":{"shasum":"1230e0fe7f9c8bddb4913a0c2deb2669f6e6760c","tarball":"https://registry.npmjs.org/@adginr/google-ads-mcp/-/google-ads-mcp-0.3.0.tgz","fileCount":14,"integrity":"sha512-HFv/1CLaY/iEimLKGyfDkF5MZL8K86i0Wl4uTh9i7/KMg3jbMsruDlHItoL0k70B1kDWQi5GwH0LkzOkp8wu1w==","signatures":[{"sig":"MEUCIQC6gViD5V/M4rH/RQgo2Mg6M1Y74lWJcPvWSQP02SAbKgIgbr7XCokAzyUFQMD6Nw5kuq9yj0nbkDUHf9Oni6scJ8Q=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIBZhPFNzRAm2nb2HPTC+rRBeimSpBsudCcPPUVSBT1PlAiAPN7gfEnlLU8LCniKj07P9By6rQnui8LYCuPsm6xwA1g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@adginr%2fgoogle-ads-mcp@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":36141},"type":"module","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./package.json":"./package.json"},"scripts":{"build":"tsdown","start":"node src/cli.ts","typecheck":"tsc --noEmit","check:package":"publint --strict"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"61bc1d6b-8059-4c56-9a3c-a96dd2089b59"}},"repository":{"url":"git+https://github.com/adginr/google-ads-rest.git","type":"git","directory":"packages/mcp"},"description":"Model Context Protocol server for the Google Ads API over REST: GAQL search, keywords, ads, assets, budgets.","directories":{},"_nodeVersion":"24.21.0","dependencies":{"zod":"^4.6.7","@adginr/google-ads-rest":"^0.3.0","@modelcontextprotocol/node":"^2.1.1","@modelcontextprotocol/server":"^2.3.1"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/google-ads-mcp_0.3.0_1792236692972_0.38516586787045837","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"_id":"@adginr/google-ads-mcp@0.4.0","bin":{"google-ads-mcp":"./dist/cli.js"},"bugs":"https://github.com/adginr/google-ads-rest/issues","dist":{"shasum":"b8cb4c009265ab7689fa118fd76a3754ab972ee5","tarball":"https://registry.npmjs.org/@adginr/google-ads-mcp/-/google-ads-mcp-0.4.0.tgz","fileCount":14,"integrity":"sha512-kKWtvJqPpBC0I8nSL6zp96Z8oQD/ofra7UmWaygxsEaDlH9NkSHjRG/+kgwsxnYhBvwXwalKhZHXFUXb5nGvHQ==","signatures":[{"sig":"MEYCIQCsB9i7pCfM0Ber7DxqUUyHxnOUOVcMQSKhaRBp1QjsJwIhAMiSFrRy2U23qZ1oAT8JfyIxDe8WsmGdkRc4UrcXMsiB","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICo2hOiyN7Y+FFhhw3+Jz6XBDD9ma0lRdkSH+BRRtWx5AiEAwc1Vi1yrgCLN0SrwJZS7J6pisvLWYYePL7kEa1iG9tA="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@adginr%2fgoogle-ads-mcp@0.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":37805},"name":"@adginr/google-ads-mcp","type":"module","author":"Kolin (https://adginr.com)","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./package.json":"./package.json"},"license":"Apache-2.0","scripts":{"build":"tsdown","start":"node src/cli.ts","typecheck":"tsc --noEmit","check:package":"publint --strict"},"version":"0.4.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"61bc1d6b-8059-4c56-9a3c-a96dd2089b59"}},"homepage":"https://github.com/adginr/google-ads-rest/tree/main/packages/mcp#readme","keywords":["google-ads","google-ads-api","mcp","model-context-protocol","mcp-server","claude","ai-agent"],"repository":{"url":"git+https://github.com/adginr/google-ads-rest.git","type":"git","directory":"packages/mcp"},"description":"Model Context Protocol server for the Google Ads API over REST: GAQL search, keywords, ads, assets, budgets.","directories":{},"maintainers":[{"name":"adginr","email":"nickolai.zt@gmail.com"}],"_nodeVersion":"24.21.0","dependencies":{"zod":"^4.6.7","@adginr/google-ads-rest":"^0.4.0","@modelcontextprotocol/node":"^2.1.1","@modelcontextprotocol/server":"^2.3.1"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/google-ads-mcp_0.4.0_1792254932299_0.7984461069915896"}}},"time":{"created":"2026-10-15T17:15:22.359Z","modified":"2026-10-17T16:35:32.729Z","0.0.0-stage":"2026-10-15T17:15:22.359Z","0.1.0":"2026-10-15T17:16:22.678Z","0.2.0":"2026-10-16T12:35:58.918Z","0.3.0":"2026-10-17T11:31:33.056Z","0.4.0":"2026-10-17T16:35:32.394Z"},"bugs":"https://github.com/adginr/google-ads-rest/issues","author":"Kolin (https://adginr.com)","license":"Apache-2.0","homepage":"https://github.com/adginr/google-ads-rest/tree/main/packages/mcp#readme","keywords":["google-ads","google-ads-api","mcp","model-context-protocol","mcp-server","claude","ai-agent"],"repository":{"url":"git+https://github.com/adginr/google-ads-rest.git","type":"git","directory":"packages/mcp"},"description":"Model Context Protocol server for the Google Ads API over REST: GAQL search, keywords, ads, assets, budgets.","maintainers":[{"name":"adginr","email":"nickolai.zt@gmail.com"}],"readme":"# @adginr/google-ads-mcp\n\n[Model Context Protocol](https://modelcontextprotocol.io) server for the Google Ads API. It lets an AI\nassistant report on and manage a Google Ads account: GAQL reporting, keyword research, keywords, responsive\nsearch ads, budgets, callouts and sitelinks.\n\n- Runs over the Google Ads **REST** API: no gRPC, no Python, no developer token.\n- **Safe by default.** New ad groups and ads start paused, every change supports `validateOnly` dry runs,\n  removals are marked destructive so clients ask first, and `--read-only` hides every mutating tool.\n- stdio for local clients, Streamable HTTP for everything else.\n\n## 1. Get credentials\n\n1. In a Google Cloud project with the **Google Ads API** enabled, open\n   [Google Auth Platform → Clients](https://console.cloud.google.com/auth/clients) and create an OAuth client\n   of type **Desktop app**. Download its JSON.\n2. Sign in once:\n\n   ```bash\n   npx @adginr/google-ads-mcp auth ~/Downloads/client_secret_….json\n   ```\n\n   This opens Google sign-in, then writes `GOOGLE_ADS_CLIENT_ID`, `GOOGLE_ADS_CLIENT_SECRET` and\n   `GOOGLE_ADS_REFRESH_TOKEN` to `.env` in the current directory and lists the accounts you can reach.\n\n3. If your accounts sit under a manager (MCC) account, add `GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890` to\n   `.env`.\n\n## 2. Connect a client\n\nThe server reads `GOOGLE_ADS_*` from the environment and from `.env` in its working directory\n(or `--env-file <path>`).\n\n**Claude Code**\n\n```bash\nclaude mcp add google-ads -- npx -y @adginr/google-ads-mcp --env-file /path/to/.env\n```\n\n**Claude Desktop, Cursor, Windsurf** and other clients with a JSON config:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-ads\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@adginr/google-ads-mcp\"],\n      \"env\": {\n        \"GOOGLE_ADS_CLIENT_ID\": \"…\",\n        \"GOOGLE_ADS_CLIENT_SECRET\": \"…\",\n        \"GOOGLE_ADS_REFRESH_TOKEN\": \"…\",\n        \"GOOGLE_ADS_LOGIN_CUSTOMER_ID\": \"1234567890\"\n      }\n    }\n  }\n}\n```\n\n**opencode** (`opencode.json`):\n\n```json\n{\n  \"mcp\": {\n    \"google-ads\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@adginr/google-ads-mcp\", \"--env-file\", \"/path/to/.env\"]\n    }\n  }\n}\n```\n\n**Streamable HTTP**:\n\n```bash\nnpx @adginr/google-ads-mcp --http --port 8765   # http://127.0.0.1:8765/mcp\n```\n\nThe HTTP transport listens on `127.0.0.1` only and has no authentication. Put an authenticating proxy in\nfront of it before exposing it anywhere.\n\n## Options\n\n| Flag / variable                             | Effect                                                 |\n| ------------------------------------------- | ------------------------------------------------------ |\n| `--read-only`, `GOOGLE_ADS_MCP_READ_ONLY=1` | Register only the tools that never change the account. |\n| `--http`, `--port <n>`                      | Serve Streamable HTTP instead of stdio (default 8765). |\n| `--env-file <path>`, `GOOGLE_ADS_ENV_FILE`  | Env file to load, and to write on `auth`.              |\n\n## Tools\n\n| Tool                                                   | What it does                                                                                             |\n| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |\n| `list_accessible_customers`                            | Account IDs the signed-in user can access.                                                               |\n| `list_campaigns`                                       | Campaigns with status, budget and performance over a date range.                                         |\n| `get_campaign_snapshot`                                | One campaign in full: settings, budget, targeting, ad groups, keywords, ads, negatives and assets.       |\n| `get_resource_metadata`                                | Selectable / filterable / sortable fields of a GAQL resource.                                            |\n| `search`                                               | Structured GAQL query (fields, resource, conditions, ordering, limit).                                   |\n| `suggest_geo_targets`                                  | Location IDs from (partial) place names.                                                                 |\n| `generate_keyword_ideas`                               | Keyword Planner ideas from keywords, a page or a whole site, with monthly volumes, competition and bids. |\n| `create_campaign_budget`                               | New daily budget, shared or for one campaign.                                                            |\n| `create_search_campaign`                               | Search campaign with budget, bidding, networks, dates, locations and languages in one step; paused.      |\n| `update_campaign`                                      | Rename a campaign or switch its bidding strategy.                                                        |\n| `pause_campaign`, `enable_campaign`                    | Change campaign status.                                                                                  |\n| `update_campaign_budget`                               | Change the daily budget; refuses shared budgets unless confirmed.                                        |\n| `create_ad_group`                                      | New ad group, paused by default.                                                                         |\n| `update_ad_group`                                      | Rename an ad group or change its default CPC bid.                                                        |\n| `update_ad_group_status`                               | Enable, pause or remove an ad group.                                                                     |\n| `add_keywords_to_ad_group`                             | Add keywords in one match type, optionally skipping existing ones.                                       |\n| `update_keyword_status`                                | Pause or enable keywords.                                                                                |\n| `remove_keyword_from_ad_group`                         | Remove one positive keyword (verified first; never touches negatives).                                   |\n| `add_negative_keyword_to_ad_group`                     | Add an ad group negative keyword.                                                                        |\n| `add_negative_keyword_to_campaign`                     | Add a campaign negative keyword.                                                                         |\n| `remove_negative_keyword_from_campaign`                | Remove a campaign negative keyword.                                                                      |\n| `list_negative_keyword_lists`                          | Shared negative keyword lists, optionally with their keywords.                                           |\n| `create_negative_keyword_list`                         | New shared list, optionally with keywords and campaigns.                                                 |\n| `add_keywords_to_negative_keyword_list`, `remove_…`    | Add or remove keywords of a shared list.                                                                 |\n| `attach_negative_keyword_list`, `detach_…`             | Apply a shared list to campaigns or stop applying it.                                                    |\n| `list_ads_in_ad_group`                                 | Ads with full responsive search ad copy, pins and Ad Strength.                                           |\n| `create_responsive_search_ad`                          | New RSA, paused by default, with pin checks and warnings.                                                |\n| `update_ad_status`                                     | Enable, pause or remove an ad.                                                                           |\n| `list_callouts`, `create_callouts`                     | Read callout links; create callout assets.                                                               |\n| `attach_callouts_to_campaign` / `_account`             | Link callouts.                                                                                           |\n| `update_callout_link_status`, `remove_callout_links`   | Pause, enable or unlink callouts.                                                                        |\n| `list_sitelinks`, `create_sitelinks`                   | Read sitelink links; create sitelink assets.                                                             |\n| `attach_sitelinks_to_campaign` / `_ad_group`           | Link sitelinks.                                                                                          |\n| `update_sitelink_link_status`, `remove_sitelink_links` | Pause, enable or unlink sitelinks.                                                                       |\n\nEvery mutating tool takes `validateOnly: true` for a dry run. Money inputs (`dailyBudget`, `cpcBid`) are in the\naccount currency, not micros.\n\n## Resources\n\n`google-ads://docs/release-notes`, `google-ads://docs/metrics`, `google-ads://docs/segments` and\n`google-ads://docs/discovery-document`: Google Ads API reference pages, fetched live.\n\n## Embedding\n\n```ts\nimport { GoogleAdsClient } from '@adginr/google-ads-rest';\nimport { createGoogleAdsMcpServer } from '@adginr/google-ads-mcp';\nimport { createMcpHandler } from '@modelcontextprotocol/server';\n\nconst ads = GoogleAdsClient.fromEnv();\nconst handler = createMcpHandler(() => createGoogleAdsMcpServer({ ads, readOnly: true }));\n// e.g. in a web framework route: return handler.fetch(request);\n```\n\n`createMcpHandler` comes from `@modelcontextprotocol/server`; any of its transports works.\n\n## License\n\nApache-2.0. Not affiliated with Google.\n","readmeFilename":""}