Skip to main content
Glama
Querya

Querya

Official
by extractify

Querya: Google Ads MCP server

Querya is a hosted MCP server that connects AI agents to your Google Ads accounts: Claude, ChatGPT, Cursor, VS Code, Gemini CLI, Cline and any client that speaks MCP over Streamable HTTP.

Ask in plain language and your agent answers with live data: performance by campaign, ad group, keyword or search term; wasted spend and negative keyword candidates; Quality Score; impression share; budget pacing; conversion actions; change history; policy issues and Google Ads Recommendations. Keyword research uses Google Keyword Planner: ideas, metrics and forecasts by location and language.

Changes are safe by design. Creating campaigns, ads, keywords, negatives, assets and audiences, or editing budgets, bids, targeting and status, never applies directly. Querya first returns a preview validated by Google Ads, with the risk level and the daily spend impact. Nothing changes until you confirm. New campaigns are always created paused. Per-account guardrails cap budgets and bids and block removals by default. Every change is logged and can be undone.

  • Server URL: https://mcp.querya.io/mcp (Streamable HTTP)

  • Auth: OAuth 2.1 with PKCE. Dynamic client registration and Client ID Metadata Documents are supported, so there is no key to paste. You sign in with Google and choose exactly which Google Ads accounts the agent can reach.

  • Plans: Free: 1 account, read-only. Pro and Max: more accounts, manager (MCC) accounts and changes. See querya.io.

This repository holds the public listing files (MCP Registry server.json, Gemini CLI extension). The server itself is hosted by Querya; there is nothing to install or run.

Connect

Claude (claude.ai and Claude Desktop)

Settings → Connectors → Add custom connector → URL https://mcp.querya.io/mcp.

Claude Code

claude mcp add --transport http querya https://mcp.querya.io/mcp

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "querya": { "url": "https://mcp.querya.io/mcp" }
  }
}

VS Code (GitHub Copilot)

.vscode/mcp.json:

{
  "servers": {
    "querya": { "type": "http", "url": "https://mcp.querya.io/mcp" }
  }
}

Gemini CLI

gemini extensions install https://github.com/extractify/querya-mcp

Cline, Windsurf and other clients

Add a remote MCP server with the URL https://mcp.querya.io/mcp. The client opens the Querya sign-in in your browser the first time.

ChatGPT

Settings → Apps & Connectors → developer mode → Create → URL https://mcp.querya.io/mcp, authentication OAuth.

Related MCP server: Google Ads MCP

Example prompts

  • "How did my campaigns do last week compared with the week before?"

  • "Which search terms spent money without converting in the last 30 days? Prepare negatives for the worst ones."

  • "Find keyword ideas for 'curso de inglês online' in Brazil and forecast clicks and cost for R$50/day."

  • "Raise the budget of the Brand campaign to R$80/day." (shows a preview; nothing changes until you confirm)

  • "Who changed what in this account this week?"

Tools (59)

Read tools have readOnlyHint. Write tools only prepare a validated plan; confirm_change_plan (destructiveHint) is the one that changes the account, after your explicit confirmation.

Tool

What it does

list_accounts

List the Google Ads accounts the user has enabled for Querya, with currency, time zone, whether each one is a manager (MCC) account, and whether write tools are allowed on it.

get_account_hierarchy

Show the manager (MCC) tree: every Google Ads account Querya found for the user, its parent manager, and whether it is enabled in Querya.

get_account_overview

Quick health check of one account: status, spend, clicks, conversions, CPA and ROAS for the period, number of active campaigns, the top 5 campaigns by cost, and counts of disapproved or limited ads.

set_default_account

Choose the account used when other tools are called without customer_id.

refresh_accounts

Re-read the accounts the user's Google login can access (including MCC sub-accounts).

run_gaql

Run a custom read-only Google Ads Query Language (GAQL) query when no ready-made report fits.

describe_gaql_resource

List the selectable fields (with type, filterable/sortable and enum values), the compatible metrics and segments, and the attributed resources of a GAQL resource, straight from Google Ads metadata.

get_performance_report

Ready-made performance report by level (account, campaign, ad_group, ad, keyword, bidding_strategy) for a period: impressions, clicks, cost, conversions, value, CTR, avg CPC, CPA and ROAS, optionally split by date or device, with account totals and, if compare=true, change vs the previous period of the same length.

get_search_terms

Search terms that triggered ads, with matched keyword, cost and conversions, sorted by cost.

get_asset_performance

Performance of ad assets in the period.

get_keyword_quality

Quality Score (1–10) and its components — expected CTR, ad relevance, landing page experience — for enabled keywords with traffic in the period, sorted by cost, with the impression-weighted average.

get_impression_share

Search impression share per Search campaign and the share lost to budget and to rank (ad rank / Quality Score), plus top and absolute-top shares, in percent.

get_budget_pacing

Month-to-date spend of each enabled campaign against its budget (daily budget × days in month), with a linear projection to month end.

get_change_history

Changes made to the account, newest first: when, what resource, operation, which tool (web, API, scripts, Querya…) and who.

get_change_timeline

A readable timeline of what changed in the account and who did it, grouped by day: plain-language sentences ("raised the budget of "Brand" from $50 to $80/day"), current campaign and ad group names, similar changes grouped together, and the change_id of changes made through Querya (for undo_change).

get_policy_issues

Ads that are disapproved or limited by Google policy, with policy topics and the evidence text.

get_conversion_actions

Conversion actions of the account (status, type, category, counting, primary or secondary) with all conversions and value in the period.

get_recommendations

Google Ads Recommendations: Google's active (not dismissed) recommendations with estimated weekly impact on impressions, clicks, cost and conversions, sorted by conversion gain.

generate_keyword_ideas

Keyword ideas from Google Keyword Planner for seed keywords, a landing page URL, both, or a whole site: average monthly searches, last-month volume, 3-month and year-over-year trend, competition and the top-of-page bid range in the account currency.

get_keyword_metrics

Historical Keyword Planner metrics for a list of keywords you already have (up to 1000): average monthly searches, trend, competition, top-of-page bids and average CPC; close variants are grouped.

forecast_keywords

Forecast clicks, cost, average CPC and (when available) conversions and CPA for a NEW Search campaign with the given keywords, daily budget, locations and language, starting tomorrow for 7–90 days.

search_geo_targets

Find Google Ads location IDs by name (country, state, city, postal code), with canonical name, type and reach.

search_languages

List Google Ads language IDs and codes, optionally filtered by name or code.

create_search_campaign

Create a complete Google Search campaign in one step: budget, campaign (ALWAYS created PAUSED), locations, languages, bidding strategy, ad groups with keywords and responsive search ads, and optional campaign negative keywords.

create_ad_group

Create an ad group in an existing Search campaign, optionally with keywords and responsive search ads.

create_responsive_search_ad

Create a responsive search ad (3–15 headlines up to 30 characters, 2–4 descriptions up to 90, optional pins and paths).

add_keywords

Add keywords to an ad group, with match type and optional CPC/final URL.

add_negative_keywords

Add negative keywords to a campaign, an ad group or a shared negative list (level + target_id).

create_negative_keyword_list

Create a shared negative keyword list and attach it to campaigns.

set_status

Enable, pause or remove campaigns, ad groups, ads or keywords (batch).

update_budget

Change a campaign's daily budget.

update_bidding_strategy

Switch a campaign bidding strategy (MANUAL_CPC, MAXIMIZE_CLICKS, MAXIMIZE_CONVERSIONS, TARGET_CPA, MAXIMIZE_CONVERSION_VALUE, TARGET_ROAS) and targets, or attach the campaign to an existing portfolio strategy with portfolio_id (see create_bidding_strategy).

update_bids

Change max CPC bids of ad groups or keywords (Manual CPC).

update_targeting

Change campaign targeting: add/remove locations and languages (names or IDs), replace the ad schedule, set device bid adjustments (% from -100 to +900).

update_ad

Edit a responsive search ad: replace headlines and/or descriptions, paths or the final URL.

update_keywords

Change keyword match type (creates the new keyword and pauses the old one, since match type cannot be edited) or final URL.

apply_recommendation

Apply Google Ads Recommendations by recommendation_id (from get_recommendations).

dismiss_recommendation

Dismiss Google Ads Recommendations by recommendation_id (from get_recommendations).

create_performance_max_campaign

Create a Performance Max campaign in one step: budget, campaign (ALWAYS created PAUSED), locations, languages, bidding (MAXIMIZE_CONVERSIONS / TARGET_CPA / MAXIMIZE_CONVERSION_VALUE / TARGET_ROAS) and one asset group with texts, images, logo, final URL and optional search themes as audience signal.

create_assets

Create ad assets (extensions) and link them to the account, a campaign or an ad group: sitelinks, callouts, a structured snippet, a call asset, images and business logos (public https URLs, checked by Querya).

create_conversion_action

Create a conversion action.

upload_offline_conversions

Import conversions (e.g.

create_bidding_strategy

Create a portfolio bidding strategy shared by several campaigns: TARGET_CPA, TARGET_ROAS, MAXIMIZE_CONVERSIONS (optional target CPA), MAXIMIZE_CONVERSION_VALUE (optional target ROAS) or MAXIMIZE_CLICKS (optional CPC ceiling).

bulk_mutate

Advanced: apply a batch of raw Google Ads API mutate operations (GoogleAdsService.Mutate, REST JSON in camelCase, see https://developers.google.com/google-ads/api/docs/mutating/overview) when no specific tool fits, e.g.

create_audience

Create an audience.

get_audience_status

Size for Search/Display, match rate and upload job status of an audience list (e.g.

create_rule

Create a rule that Querya runs on a schedule (daily at an hour of the account time zone, or hourly).

list_rules

List scheduled rules with their last runs (matches, plan created, applied or failed).

delete_rule

Delete a scheduled rule (pending plans it created stay until they expire).

create_alert

Create an email alert for an account (all plans).

list_alerts

List email alerts with when they were last checked and triggered.

delete_alert

Delete an email alert.

confirm_change_plan

Apply a pending change plan AFTER the user explicitly confirmed the preview.

cancel_change_plan

Discard a pending change plan.

list_change_plans

List pending (not yet confirmed) change plans of this user.

list_change_log

Changes applied through Querya (newest first) with before/after, whether they can be undone, and the Google request id.

undo_change

Create a change plan that reverts a change made with Querya (change_id from list_change_log).

get_guardrails

Show the safety limits of an account: max daily budget (null = 2× the largest current budget), max budget increase per change, max CPC, auto-apply of low-risk changes, removal allowed, allowed/blocked tools.

set_guardrails

Change the safety limits of an account (owners and admins only).

Security and privacy

  • Google refresh tokens are envelope-encrypted; Querya never shows them to the agent or to anyone else.

  • Each tool call checks that the account is one you enabled for Querya.

  • Content from the account (campaign names, ad texts, search terms) is returned as data, never as instructions.

  • Querya does not store ad metrics, except a short-lived cache and, for enabled accounts, a copy of the Google Ads change history.

Privacy policy · Terms of service · Docs

Support

suporte@extractify.com.br

Querya is a product of Extractify Tecnologia Ltda. Google Ads is a trademark of Google LLC; Querya is not affiliated with or endorsed by Google.

License

The files in this repository are MIT licensed. The Querya service is proprietary.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to manage Google Ads accounts by providing tools for querying account data and performing write operations such as updating campaign budgets, statuses, and bidding strategies.
      2
      Apache 2.0
    • F
      license
      A
      quality
      D
      maintenance
      Enables AI agents to manage Google Ads campaigns (Search and UAC) through natural language, with read tools always available and guarded write operations for budgets, campaigns, ad groups, and keywords.
      3
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to manage and analyze Google Ads campaigns through tools for listing campaigns, retrieving settings, performance metrics, ad groups, and running custom GAQL queries.
      81 npm
      MIT