Repository avatar
AI Tools
v1.0.0
active

querya

io.querya/querya

Google Ads for AI agents: live reports, Keyword Planner, and changes with preview, confirm and undo.

Documentation

Querya

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.

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.

ToolWhat it does
list_accountsList 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_hierarchyShow 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_overviewQuick 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_accountChoose the account used when other tools are called without customer_id.
refresh_accountsRe-read the accounts the user's Google login can access (including MCC sub-accounts).
run_gaqlRun a custom read-only Google Ads Query Language (GAQL) query when no ready-made report fits.
describe_gaql_resourceList 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_reportReady-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_termsSearch terms that triggered ads, with matched keyword, cost and conversions, sorted by cost.
get_asset_performancePerformance of ad assets in the period.
get_keyword_qualityQuality 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_shareSearch 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_pacingMonth-to-date spend of each enabled campaign against its budget (daily budget × days in month), with a linear projection to month end.
get_change_historyChanges made to the account, newest first: when, what resource, operation, which tool (web, API, scripts, Querya…) and who.
get_change_timelineA 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_issuesAds that are disapproved or limited by Google policy, with policy topics and the evidence text.
get_conversion_actionsConversion actions of the account (status, type, category, counting, primary or secondary) with all conversions and value in the period.
get_recommendationsGoogle Ads Recommendations: Google's active (not dismissed) recommendations with estimated weekly impact on impressions, clicks, cost and conversions, sorted by conversion gain.
generate_keyword_ideasKeyword 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_metricsHistorical 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_keywordsForecast 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_targetsFind Google Ads location IDs by name (country, state, city, postal code), with canonical name, type and reach.
search_languagesList Google Ads language IDs and codes, optionally filtered by name or code.
create_search_campaignCreate 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_groupCreate an ad group in an existing Search campaign, optionally with keywords and responsive search ads.
create_responsive_search_adCreate a responsive search ad (3–15 headlines up to 30 characters, 2–4 descriptions up to 90, optional pins and paths).
add_keywordsAdd keywords to an ad group, with match type and optional CPC/final URL.
add_negative_keywordsAdd negative keywords to a campaign, an ad group or a shared negative list (level + target_id).
create_negative_keyword_listCreate a shared negative keyword list and attach it to campaigns.
set_statusEnable, pause or remove campaigns, ad groups, ads or keywords (batch).
update_budgetChange a campaign's daily budget.
update_bidding_strategySwitch 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_bidsChange max CPC bids of ad groups or keywords (Manual CPC).
update_targetingChange campaign targeting: add/remove locations and languages (names or IDs), replace the ad schedule, set device bid adjustments (% from -100 to +900).
update_adEdit a responsive search ad: replace headlines and/or descriptions, paths or the final URL.
update_keywordsChange keyword match type (creates the new keyword and pauses the old one, since match type cannot be edited) or final URL.
apply_recommendationApply Google Ads Recommendations by recommendation_id (from get_recommendations).
dismiss_recommendationDismiss Google Ads Recommendations by recommendation_id (from get_recommendations).
create_performance_max_campaignCreate 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_assetsCreate 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_actionCreate a conversion action.
upload_offline_conversionsImport conversions (e.g.
create_bidding_strategyCreate 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_mutateAdvanced: 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_audienceCreate an audience.
get_audience_statusSize for Search/Display, match rate and upload job status of an audience list (e.g.
create_ruleCreate a rule that Querya runs on a schedule (daily at an hour of the account time zone, or hourly).
list_rulesList scheduled rules with their last runs (matches, plan created, applied or failed).
delete_ruleDelete a scheduled rule (pending plans it created stay until they expire).
create_alertCreate an email alert for an account (all plans).
list_alertsList email alerts with when they were last checked and triggered.
delete_alertDelete an email alert.
confirm_change_planApply a pending change plan AFTER the user explicitly confirmed the preview.
cancel_change_planDiscard a pending change plan.
list_change_plansList pending (not yet confirmed) change plans of this user.
list_change_logChanges applied through Querya (newest first) with before/after, whether they can be undone, and the Google request id.
undo_changeCreate a change plan that reverts a change made with Querya (change_id from list_change_log).
get_guardrailsShow 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_guardrailsChange 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.

No installation packages available.

Remote