npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@adginr/google-ads-mcp

v0.4.0

Published

Model Context Protocol server for the Google Ads API over REST: GAQL search, keywords, ads, assets, budgets.

Readme

@adginr/google-ads-mcp

Model Context Protocol server for the Google Ads API. It lets an AI assistant report on and manage a Google Ads account: GAQL reporting, keyword research, keywords, responsive search ads, budgets, callouts and sitelinks.

  • Runs over the Google Ads REST API: no gRPC, no Python, no developer token.
  • Safe by default. New ad groups and ads start paused, every change supports validateOnly dry runs, removals are marked destructive so clients ask first, and --read-only hides every mutating tool.
  • stdio for local clients, Streamable HTTP for everything else.

1. Get credentials

  1. In a Google Cloud project with the Google Ads API enabled, open Google Auth Platform → Clients and create an OAuth client of type Desktop app. Download its JSON.

  2. Sign in once:

    npx @adginr/google-ads-mcp auth ~/Downloads/client_secret_….json

    This opens Google sign-in, then writes GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET and GOOGLE_ADS_REFRESH_TOKEN to .env in the current directory and lists the accounts you can reach.

  3. If your accounts sit under a manager (MCC) account, add GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890 to .env.

2. Connect a client

The server reads GOOGLE_ADS_* from the environment and from .env in its working directory (or --env-file <path>).

Claude Code

claude mcp add google-ads -- npx -y @adginr/google-ads-mcp --env-file /path/to/.env

Claude Desktop, Cursor, Windsurf and other clients with a JSON config:

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "@adginr/google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_CLIENT_ID": "…",
        "GOOGLE_ADS_CLIENT_SECRET": "…",
        "GOOGLE_ADS_REFRESH_TOKEN": "…",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890"
      }
    }
  }
}

opencode (opencode.json):

{
  "mcp": {
    "google-ads": {
      "type": "local",
      "command": ["npx", "-y", "@adginr/google-ads-mcp", "--env-file", "/path/to/.env"]
    }
  }
}

Streamable HTTP:

npx @adginr/google-ads-mcp --http --port 8765   # http://127.0.0.1:8765/mcp

The HTTP transport listens on 127.0.0.1 only and has no authentication. Put an authenticating proxy in front of it before exposing it anywhere.

Options

| Flag / variable | Effect | | ------------------------------------------- | ------------------------------------------------------ | | --read-only, GOOGLE_ADS_MCP_READ_ONLY=1 | Register only the tools that never change the account. | | --http, --port <n> | Serve Streamable HTTP instead of stdio (default 8765). | | --env-file <path>, GOOGLE_ADS_ENV_FILE | Env file to load, and to write on auth. |

Tools

| Tool | What it does | | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | | list_accessible_customers | Account IDs the signed-in user can access. | | list_campaigns | Campaigns with status, budget and performance over a date range. | | get_campaign_snapshot | One campaign in full: settings, budget, targeting, ad groups, keywords, ads, negatives and assets. | | get_resource_metadata | Selectable / filterable / sortable fields of a GAQL resource. | | search | Structured GAQL query (fields, resource, conditions, ordering, limit). | | suggest_geo_targets | Location IDs from (partial) place names. | | generate_keyword_ideas | Keyword Planner ideas from keywords, a page or a whole site, with monthly volumes, competition and bids. | | create_campaign_budget | New daily budget, shared or for one campaign. | | create_search_campaign | Search campaign with budget, bidding, networks, dates, locations and languages in one step; paused. | | update_campaign | Rename a campaign or switch its bidding strategy. | | pause_campaign, enable_campaign | Change campaign status. | | update_campaign_budget | Change the daily budget; refuses shared budgets unless confirmed. | | create_ad_group | New ad group, paused by default. | | update_ad_group | Rename an ad group or change its default CPC bid. | | update_ad_group_status | Enable, pause or remove an ad group. | | add_keywords_to_ad_group | Add keywords in one match type, optionally skipping existing ones. | | update_keyword_status | Pause or enable keywords. | | remove_keyword_from_ad_group | Remove one positive keyword (verified first; never touches negatives). | | add_negative_keyword_to_ad_group | Add an ad group negative keyword. | | add_negative_keyword_to_campaign | Add a campaign negative keyword. | | remove_negative_keyword_from_campaign | Remove a campaign negative keyword. | | list_negative_keyword_lists | Shared negative keyword lists, optionally with their keywords. | | create_negative_keyword_list | New shared list, optionally with keywords and campaigns. | | add_keywords_to_negative_keyword_list, remove_… | Add or remove keywords of a shared list. | | attach_negative_keyword_list, detach_… | Apply a shared list to campaigns or stop applying it. | | list_ads_in_ad_group | Ads with full responsive search ad copy, pins and Ad Strength. | | create_responsive_search_ad | New RSA, paused by default, with pin checks and warnings. | | update_ad_status | Enable, pause or remove an ad. | | list_callouts, create_callouts | Read callout links; create callout assets. | | attach_callouts_to_campaign / _account | Link callouts. | | update_callout_link_status, remove_callout_links | Pause, enable or unlink callouts. | | list_sitelinks, create_sitelinks | Read sitelink links; create sitelink assets. | | attach_sitelinks_to_campaign / _ad_group | Link sitelinks. | | update_sitelink_link_status, remove_sitelink_links | Pause, enable or unlink sitelinks. |

Every mutating tool takes validateOnly: true for a dry run. Money inputs (dailyBudget, cpcBid) are in the account currency, not micros.

Resources

google-ads://docs/release-notes, google-ads://docs/metrics, google-ads://docs/segments and google-ads://docs/discovery-document: Google Ads API reference pages, fetched live.

Embedding

import { GoogleAdsClient } from '@adginr/google-ads-rest';
import { createGoogleAdsMcpServer } from '@adginr/google-ads-mcp';
import { createMcpHandler } from '@modelcontextprotocol/server';

const ads = GoogleAdsClient.fromEnv();
const handler = createMcpHandler(() => createGoogleAdsMcpServer({ ads, readOnly: true }));
// e.g. in a web framework route: return handler.fetch(request);

createMcpHandler comes from @modelcontextprotocol/server; any of its transports works.

License

Apache-2.0. Not affiliated with Google.