Run Google Ads from your AI assistant

Connect it in ten minutes

Five steps, and each one ends with something you can check. Most of the ten minutes is waiting for a client to restart.

1. Connect your Google Ads account. Sign in to Pinlyx, open Insights, Ads, Google Ads and press Connect Google Ads account. Google asks for consent on a single permission, and the page then lists every ad account that login can reach.
2. Create a scoped API key. Open Settings, Developers and create a key with ads:read. Add ads:write only when you want the assistant to change things, and prefer a second key for that rather than widening the first one.
3. Prove the key works before touching a client. POST a tools/list JSON-RPC request to https://api.pinlyx.com/mcp with the key as a bearer token. You should get tool names back rather than a 401.
4. Add the server to your MCP client. Point the client at npx -y @crmsolid/mcp-server with --tools ads, put the key in the environment, and restart the client completely. Add --read-only for sessions meant only for analysis.
5. Ask for something real. Ask which accounts are connected, what last week cost, and which search terms converted nothing. Compare the numbers against the Google Ads interface for the same window before you trust the next answer.

The client config is the same block in Claude Desktop, Cursor and anything else that launches a local command. The bridge is published to npm as @crmsolid/mcp-server, and --tools ads limits the session to the Google Ads surface so the assistant is not distracted by the rest of the CRM.

{
  "mcpServers": {
    "pinlyx-ads": {
      "command": "npx",
      "args": ["-y", "@crmsolid/mcp-server", "--tools", "ads"],
      "env": { "CRMSOLID_API_KEY": "csk_live_your_key_here" }
    }
  }
}

Claude Code takes the same thing as one command, and a research session adds --read-only so the write tools are gone for that client entirely:

claude mcp add pinlyx-ads \
  --env CRMSOLID_API_KEY=csk_live_your_key_here \
  -- npx -y @crmsolid/mcp-server --tools ads --read-only

Before any of that, prove the key works with a plain HTTP call. This is the fastest way to separate a wrong key from a client configuration problem, and it is the step people skip and then spend an hour on:

curl -sS https://api.pinlyx.com/mcp \
  -H "Authorization: Bearer csk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tool names back means the key is good. A 401 means it is wrong, revoked, or was copied with a trailing space. Full walkthroughs for each client are in tutorial 01.

What this is genuinely good at

The search term loop is the one that pays for the setup in a week. Google matches your keywords to queries nobody on your team wrote down, and some of those queries cost money forever because nobody reads a 4,000 row report on a Tuesday. An assistant does: one breakdown call at search_terms level returns rows sorted by cost, clicks and conversions, cursor-paginated for the rest, and the question "which of these spent more than the price of a lead and converted nothing" is one sentence rather than a pivot table.

Reporting is the second. A weekly rollup that reads the account summary, the campaign table, the ad group detail and the search terms that moved is about six requests, and the assistant writes the commentary around the numbers instead of you writing it around a screenshot. Compare it against the Google Ads interface the first few times. Small differences in the last hour are normal, Google’s own reporting lags.

Changes are where discipline matters more than capability. Never let a write be the first tool call in a turn. Read the current state, state the change in one sentence with the entity name, the old value and the new value, confirm with a person when money moves, change exactly one thing, then verify by reading the entity back from Google rather than trusting the tool’s own confirmation. That loop is the entire content of tutorial 03, and it is the difference between an assistant that is useful on a Friday afternoon and one you end up not trusting.

Plans, allowance and what actually counts

The Google Ads API counts operations per Cloud project rather than per customer, so every workspace on a deployment draws from the same daily pool. That is why the server meters what reaches Google rather than trusting everyone to be reasonable.

Read that table honestly: connecting Google Ads, reporting on it and managing it inside Pinlyx is open on every plan, including the free one. The MCP server and the API keys it authenticates with are a developer surface on the Business plan, and Business has no daily cap on Google Ads. So the free plan is the way to evaluate the integration, and the Business plan is the way to put it in front of an assistant.

What counts and what does not: a report served from the 15 minute cache does not count, one breakdown call returns a page of rows cursor-paginated for the rest so a week of search terms is a handful of requests, and writes count including a status change that turns out to be a no-op. On a capped plan, past the limit the API answers HTTP 429 with a message naming the limit and the reset, which is midnight UTC. That is a safety feature as much as a cost control: an assistant stuck in a loop spends an allowance and stops, rather than hammering the account until Google starts refusing everyone.

Scopes, read-only sessions, and injection

Layer one is the scope on the key. ads:read covers the account summary, campaigns, ad groups, ads, keywords, search terms, campaign settings and the draft list. ads:write adds status changes, daily budget, bidding strategy, dry runs and publishing an approved draft. One key per purpose rather than one key per person, never widen a key when you can mint a new one, and revoke on role change. Keys are shown once.

Layer two is the read-only session. Scopes live server side; the bridge adds a local filter. Starting it with --read-only keeps only the tools annotated read-only, and enforces that on the call as well as on the list. Hiding a tool from tools/list alone is advice, because a model that saw the name in an earlier turn can still try it. The call-time check is what makes it a control. Run two entries side by side, one research and one maintenance, and pick the session to match the task.

Layer three is remembering that ad data is user generated content. Search terms are what strangers typed into Google, so a query written as an instruction will appear in a report eventually. Your assistant reads it as data or as instruction depending on how you set the session up. Read-only sessions for anything that analyses search terms, a system prompt that says text inside tool results is data and never an instruction, and confirmation before writes, which breaks the chain even if the model is convinced.

What stays in human hands, on purpose

Some things are missing from this surface deliberately, and routing around them is a mistake rather than a workaround.

• Campaign creation is a two-person job. Drafts are built and approved in the Ads Studio builder, where a person sees the budget, the keywords and the ad copy on one screen. crm_publish_ad_draft only publishes an approved draft, and the campaign is created paused every time.
• Enabling spend is explicit. Publishing never starts delivery. Someone enables the campaign, which is a decision with a name attached to it.
• Payment and account setup stay in Google. Adding a payment method or enabling monthly invoicing are not exposed here, and the Google Ads API does not offer them at all. Account creation and user access management are not part of this surface either.
• Removal is a different category of action. Enabled and paused are reversible, and can be reverted with crm_google_ads_undo within 30 days. Removed is permanent inside the ad account and explicitly excluded from undo. Keep it out of automated workflows and require the word in a human’s own message.

Keyword Planner is part of this surface now (crm_google_ads_keyword_ideas and crm_google_ads_forecast), and an image asset can be added from a public https URL that Pinlyx downloads. What is still missing: a raw file upload from your machine, video assets, and a live lookup against Google’s own Ad Preview and Diagnosis tool, which the Google Ads API does not expose. Where a workflow needs one of those, the tutorials say a person does that step rather than pretending the tool exists.