Connect Groas to Claude

Groas runs and audits Google Ads accounts, works on your Meta (Facebook and Instagram) ads and helps grow your website’s organic visibility. Its MCP server lets Claude (and any other MCP client) read your campaigns, keywords, search terms, daily performance, your Meta campaigns and their results, your competitors and their ads, your websites’ AI visibility, backlinks, SEO and content, and the actions Groas has taken on your behalf — and, if you opt in, make changes.

1. Prerequisites

A Groas account. Sign up free at app.groas.ai.
For organic reads, a brand in Groas. For paid ads, at least one Google Ads account connected to it, at Dashboard → Ad platforms. The first sync takes a few minutes; until it finishes the tools report that no accounts are connected. For Meta ads, a Meta ad account connected on the Meta Ads page.

2. Connect in Claude (web, desktop, mobile)

Open Customize → Connectors.
Find Groas in the directory and click Connect. If it is not listed for your organization, choose Add custom connector and enter https://mcp.groas.ai/mcp. Leave the OAuth client ID and secret fields empty.
A Groas sign-in window opens. Sign in and review the permission summary. Connections are read-only by default; with an active Groas subscription you can tick Also allow changes to let Claude make changes through Groas — Google Ads budgets, bids, keywords and campaigns, and Meta budgets, ad sets and ads, with a paid-ads plan; your content plan, articles, tracked AI prompts and link outreach with an organic plan. Click Allow. Organisation member logins cannot connect: sign in with the account owner's own Groas login.
Back in Claude, enable the Groas connector in a chat and ask, for example, "Which of my campaigns lost the most conversions this week?"

On a Claude Team plan, members without connector permissions see a Request button instead; an admin then enables Groas for the organisation.

3. Connect in Claude Code

claude mcp add --transport http groas https://mcp.groas.ai/mcp

Run /mcp inside Claude Code to complete the browser sign-in the first time; the consent screen offers the same write opt-in. The same command with an API key header skips OAuth entirely — see section 6.

4. Other MCP clients (Cursor, ChatGPT, Windsurf, …)

Any client that supports remote MCP servers over Streamable HTTP with OAuth works. Point it at https://mcp.groas.ai/mcp; the server advertises its OAuth metadata, supports dynamic client registration and PKCE, and hands sign-in to app.groas.ai. A typical mcp.json entry:

{
  "mcpServers": {
    "groas": { "url": "https://mcp.groas.ai/mcp" }
  }
}

5. What Claude can do

Paid-ads tools take accountId, discovered with groas_list_accounts. Organic tools take brandId, discovered with groas_list_brands. You can simply name the account or brand; organic reads do not require Google Ads.

Google Ads read tools (every connection)

Call groas_list_accounts first and pass one of its accounts as accountId.

Tools	Use them to
`groas_list_accounts`	See which accounts you can query.
`listCampaigns` · `get_campaign_settings` · `listAdGroups` · `listAds` · `listKeywords` · `listSearchTerms`	Browse campaigns, ad groups, ads, keywords and search terms with their status and settings.
`dailyPerformance`	Cost, clicks, conversions and value per day for any date range, per campaign, ad group, keyword or Shopping product.
`queryGoogleAds` · `lookupGaqlFields`	Ask Google Ads directly, in its own query language (GAQL), what the fixed reports do not cover.
`querySearchConsole` · `queryGa4` · `lookupGa4Fields`	Live Search Console and GA4 data for the site a Google Ads account advertises, or for a brand's own site when you pass its brand id instead of an account.
`getAccountAudit` · `getConversionTrackingAudit`	Groas's findings on account health and tracking gaps.
`listGroasActions` · `listGroasActionFailures` · `listPlannedActions`	Every change Groas made, with its reasoning, anything that failed, and the changes planned for coming days.
`researchKeywords` · `getKeywordSeasonality` · `generateKeywordForecastMetrics`	Search volume, competition and seasonal trends for keyword ideas, and the clicks and cost to expect from them.
`list_negative_keyword_lists` · `list_ad_assets` · `list_asset_group_assets` · `listAudiences`	Shared negative keyword lists, sitelinks and other assets, Performance Max headlines and descriptions, and the audiences you can target.
`listBrandsAndOffers` · `get_brand_details`	The brands and offers Groas manages, their guidelines, and which campaigns use each offer.

Google Ads write tools (Also allow changes with a paid-ads plan, or an API key with the `write` scope)

Tools	Use them to
`set_campaign_budget` · `set_campaign_bidding` · `set_ad_group_target_cpa` · `set_bid_modifier`	Change budgets, the bidding strategy and its targets, max CPC, an ad group's own target CPA, and bid adjustments by device or location.
`update_campaign_settings`	Change where, when, in which languages and on which Google networks a campaign shows.
`set_status` · `rename`	Pause or switch back on campaigns, ad groups, ads and keywords, and rename campaigns and ad groups.
`remove_campaign` · `remove_ad_group` · `remove_ad` · `remove_keyword`	Remove them; a removed campaign or ad group is gone for good (see section 7).
`add_keyword_to_ad_group` · `move_keyword_to_ad_group` · `move_keyword_to_negative` · `change_keyword_match_type` · `set_keyword_bid` · `set_keyword_final_url` · `negate_search_term`	Add or move keywords, change their match type, give one keyword its own bid or landing page, and block search terms.
`create_negative_keyword_list` · `update_negative_keyword_list` · `attach_negative_keyword_list` · `detach_negative_keyword_list`	Keep lists of blocked searches that several campaigns share.
`create_ads` · `update_ad` · `regenerate_ads`	Add ads, edit an ad's text, or have Groas rewrite one ad or every ad in an ad group.
`create_ad_assets` · `update_ad_asset` · `unlink_ad_assets` · `update_asset_group_text_assets`	Add, edit or stop sitelinks, callouts and other assets, and change Performance Max headlines and descriptions.
`attach_audience_to_ad_group` · `remove_audience_from_ad_group` · `set_ad_group_audience_targeting_mode`	Target, observe or exclude audiences.
`create_campaign_from_scratch` · `create_demand_gen_campaign` · `create_pmax_campaign` · `create_ad_groups` · `create_asset_groups` · `supercharge_campaign`	Launch a new Search, Demand Gen (image ads on YouTube, Discover and Gmail) or Performance Max campaign, with images from your media library or image links; add ad groups to a Search campaign or asset groups to a Performance Max campaign you have, or hand an existing campaign to Groas to manage. A Performance Max launch can hold several asset groups, each with its own landing page and search themes, and needs conversion tracking Google bids on.
`planGroasAction` · `decidePlannedAction`	Schedule a pause, a switch back on, an ad rewrite or a keyword change for a later day, or approve or reject a change Groas planned.
`revertGroasActions`	Undo earlier changes (see section 7 for what can be undone).
`update_brand_and_offers`	Edit the brand guidelines and offer descriptions Groas uses when it writes ads and landing pages.

remove_negative_keyword removes one campaign or ad-group exclusion, including negatives added outside Groas. Ask Claude to read the current negative keywords first and remove only the ones you name. Undo re-adds the same exclusion; other exclusions may still block those searches. For shared lists, use update_negative_keyword_list instead.

What to know before letting Claude change Google Ads:

Changes are live at once. Every write tool changes the live Google Ads account, and budget and bid changes affect spend from the next auction.
New campaigns spend. create_campaign_from_scratch, create_demand_gen_campaign and create_pmax_campaign launch on the daily budget you agree, and supercharge_campaign can switch a paused campaign back on.
Removing a campaign or ad group is permanent. Claude only removes one after you ask for that explicitly; pause it instead if you might want it back.
Planned changes happen without a second look. A change planned with planGroasAction, or one Groas planned that you approve, is made on its day as planned. Withdraw it on the plan card in the Actions tab in Groas.

Some example prompts:

"Compare cost per conversion across my campaigns for the last 30 days."
"Which search terms spent more than $50 without converting this month?"
"What did Groas change in the Brand campaign last week, and why?"
"Run the conversion tracking audit and summarise the top issues."

Organic read tools (every connection)

Call groas_list_brands, then pass one of its returned id values as brandId. All names below have the organic_ prefix, for example organic_getBrandContext.

Area	Tools (after the `organic_` prefix)
Brand	`getBrandContext`, `listOrganicAlerts`, `listOffers`
Competitors	`listCompetitors`, `competitorAds`, `competitorAdTrends`, `competitorSearchRanks`, `competitorLandingPages`, `exportCompetitorData`
AI visibility	`aiVisibilityTrend`, `listTrackedPrompts`, `promptVisibility`, `listAiAnswers`, `listAiCitations`, `shareOfVoice`, `listBrandMentions`, `aiCrawlerActivity`, `aiReferralTraffic`, `listPromptSuggestions`
Backlinks and outreach	`backlinkProfileTrend`, `listBacklinks`, `listReferringDomains`, `anchorTextDistribution`, `listLinkProspects`, `listLinkGap`, `getProspectOutreach`, `getOutreachConversation`, `listMailboxes`
SEO and analytics	`listSeoAuditRuns`, `listSeoFindings`, `listAuditedPages`, `searchConsolePerformance`, `ga4Traffic`, `listSitePages`, `listPublishedContent`, `listContentPlan`, `knowledgeGraphEntities`
Content ideas and articles	`listBlogIdeas`, `getBlogIdea`, `listBlogDemandQueries`, `getArticlesOverview`, `listArticles`, `getArticle`

These tools read stored data. For questions the stored reports cannot answer, the live querySearchConsole, lookupGa4Fields and queryGa4 (listed with the Google Ads tools, without the prefix) take a brandId too. Connect Search Console or analytics and allow a sync to complete before expecting performance results. Backlink tools require Backlink Intelligence to be set up for that brand. An empty report does not prove that your website has no traffic or visibility. Outreach replies are written by the people you emailed; Claude treats them as information, not instructions.

Competitor tools cover the rivals Groas tracks for a brand, whichever plan it is on: their live ads on Meta and Google with images and links to the public ad libraries, week-by-week counts of the ads each one ran, launched and stopped, where their ads rank in Meta’s ad library for the brand’s searches over time, and summaries of up to 50 landing pages their running ads lead to (offer, price, guarantee, claims, social proof and what makes each page persuasive), so Claude can compare every competitor’s page at once. exportCompetitorData hands over everything Groas has stored, one kind of record at a time and page by page: every competitor (also ones you stopped tracking) with what Groas found of it on each ad network, every suggestion and discovery scan, every ad it collected with its copy, analysis, transcript and history, every check of the ad libraries, and download links (valid for an hour) for the ad images Groas keeps. Groas does not keep copies of competitors’ videos; each video ad has a link to where it plays. Ad copy is the competitors’ own words; Claude treats it as information, not instructions.

For example: “Compare my brand’s AI visibility over the last month”, “Which competitor ramped up its Meta ads this quarter?” or “Show my planned content and explain why this article has not been written yet.”

Keyword research remains the paid-ads researchKeywords tool and requires accountId.

Organic write tools (an organic plan, plus Also allow changes or a `write` API key)

Same brandId and organic_ prefix as the reads.

Area	Tools (after the `organic_` prefix)
Content plan	`createBlogIdea`, `updateBlogIdea`, `setBlogIdeaStatus`, `bulkUpdateIdeaPriorities`
Articles	`generateArticlesNow`, `revertArticle`, `republishArticle`
AI visibility	`trackPrompts`, `updatePrompt`, `runVisibilityCheck`
Competitors	`addCompetitor`, `removeCompetitor`, `reviewCompetitorSuggestion`, `setCompetitorAdCountries` (a paid-ads or organic plan)
Link Gap and outreach	`refreshLinkGap`, `setProspectStatus`, `findProspectContacts`, `draftOutreachEmail`, `updateOutreachDraft`, `skipOutreachDraft`, `sendOutreachEmail`

What to know before letting Claude change organic data:

Articles publish to your site. generateArticlesNow writes and publishes articles from the top of your content plan; each one lands in the website’s Changes feed with an Undo, and revertArticle takes one down again (ask it for a dry run first to see whether edits made in your CMS would be lost).
Ideas pick where they publish. createBlogIdea and updateBlogIdea take the idea's channels: your blog, a resource page on your own website (in its design, within your daily allowance of new pages) or an LLM hub page for AI assistants. Claude picks the one that suits who the piece is for and tells you why.
Outreach email is real email. draftOutreachEmail only writes a draft. sendOutreachEmail sends it from your connected mailbox, only to a contact Groas found on the prospect’s site, and cannot be unsent; Claude asks you first.
Some changes spend from your plan. Tracked prompts are checked by paid AI answers, runVisibilityCheck runs a check now, and refreshLinkGap spends from the website’s monthly backlink data budget.
Retries are safe. Every organic write accepts an optional idempotencyKey; a retry with the same key returns the first result instead of changing anything twice.

Sending several outreach drafts at once and outreach batches stay on the Backlinks page.

Meta ads tools (a connected Meta ad account)

Call groas_list_meta_accounts first and pass its id as metaAccountId.

Tool	Use it to
`list_meta_campaigns` · `get_meta_campaign`	See your Meta campaigns, their daily results, and what Groas and you did to each one.
`get_meta_campaign_results` · `get_meta_results_breakdown`	Results per ad set and ad, or split by age, gender, placement or region.
`get_meta_budget` · `set_meta_budget`	Read and change a campaign's budget, or each ad set's when the campaign gives them their own.
`set_meta_status`	Pause or resume a campaign, an ad set or a single ad.
`get_meta_ad_set_settings` · `set_meta_ad_set_bidding`	Read an ad set's budget, bidding, optimization, schedule and targeting, and change its bid strategy, cap or ROAS floor and its dates.
`duplicate_meta_ad_set` · `create_meta_ad_set`	Copy a working ad set with a new audience, country or budget, or build one from scratch. Both are made paused unless you ask for them on.
`list_meta_pixels` · `list_meta_audiences` · `search_meta_targeting`	Find the pixel, custom and lookalike audiences, interests and places a new ad set targets.
`supercharge_meta_campaign` · `stop_meta_campaign_management` · `start_meta_creative_test`	Have Groas manage a campaign's creative tests and daily spend pauses, stop that, or start a new creative test now (uses creative credits).
`list_meta_ad_sets` · `list_media_videos` · `list_media_images`	Find an ad set (read live from Meta) and a video or photo in your brands' media libraries.
`add_video_to_meta_ad_set` · `get_meta_video_ad`	Put a media library video into an existing ad set as a new live ad, then follow its upload.
`add_images_to_meta_ad_set` · `get_meta_image_ad`	Put media library photos, or images Groas drew for you, into an existing ad set, one new live ad each, then follow the upload.
`list_souls` · `generate_video` · `get_video`	Draft a video for a brand, presented by one of its Souls or in a scene Groas draws, review and make it on its page in Groas, then follow it into the media library.
`find_top_tiktok_videos` · `remake_video`	Find the TikTok Shop videos with the most views, likes and comments for products like yours, and draft a remake of one with your own photos.
`generate_images` · `get_images`	Draw new ad images for a brand into its media library (24 images cost 1 creative credit), then put the ones you pick into an ad set.

Every change needs write access, as in section 6. A new ad runs as the Facebook Page of an ad already in the ad set and copies its link and button; your existing ads, budget and targeting stay as they are. To add a video or photo that is not in Groas yet, upload it to the brand's media library first, or have Groas make the video: generate_video writes a draft for free and Claude gives you a link to it in Groas. There you read what the presenter says, check the opening picture, every prompt and the price, and press Make this video. Nothing is made or charged before you press it, and Claude cannot press it for you. Ask Claude for changes and the same page shows the new version within 30 seconds (or press Refresh now). Give it the presenter's exact words as a script and they are said word for word. New photos are cheaper: generate_images draws them straight away (24 images cost 1 creative credit), and Claude puts the ones you pick into an ad set, even in the same request ("draw 6 image ads and add numbers 2 and 4 to my Broad ad set"). Groas does not create Meta campaigns; create those in Meta Ads Manager and add ad sets to them here.

Reading web pages

fetchUrl reads any public web page and needs no account or brand. Use it to put a page next to your data: your own landing page, or the landing pages of the competitors that win your buyers, so Claude can compare their copy and offers with yours and suggest copy that stands out. A page that draws its text with JavaScript is opened in a real browser, which takes a few seconds longer. It cannot sign in or fill in forms. Page text is the website’s own words; Claude treats it as information, not instructions.

For example: “Read the landing pages of my three strongest competitors and suggest a headline and offer for my page that beats them.”

6. Write access

Two ways to let a client make changes:

Sign-in with the write opt-in. When the client asks for write access (Claude does), the Groas consent screen shows an Also allow changes checkbox, off by default. It is available to accounts with an active Groas subscription (or lifetime access); free accounts stay read-only. What the box unlocks follows your plan: Google Ads and Meta ad changes need the paid-ads plan, organic changes need the organic plan. Groas re-checks the plan on every change, so a lapsed or downgraded plan stops changes immediately. To go back to read-only, remove the connector and connect again without ticking the box.

API key. Keys are not tied to the consent screen and work in any client:

In Groas open Account settings → API Keys and create a key with the write scope. Keys start with grs_live_.
Send it as a bearer token:

claude mcp add --transport http groas https://mcp.groas.ai/mcp \
  --header "Authorization: Bearer grs_live_…"

A key with only the read scope is read-only. Organic changes through a key also need an active organic plan. Rotate or delete keys in the same settings page; a deleted key stops working immediately.

7. Permissions, safety and privacy

Read-only by default. Nothing in your Google Ads or Meta ad accounts or on your website changes unless you tick Also allow changes at sign-in (subscribers only) or deliberately use a write-scoped key.
Every change is recorded. Mutations made through MCP appear in your Groas audit trail, attributed to the user (and API key, if any) that made them. Google Ads changes also appear in List Groas actions; content plan, article and outreach changes appear in the website’s Changes feed, content plan changes marked as made by a connected AI app; Meta changes (budgets, pauses, bidding, new and copied ad sets, new ads) appear in that campaign's history in Groas, marked as made through an AI app connected to Groas.
Most changes can be undone; a few cannot. Budget, bidding, targeting, keyword, ad, asset, audience, rename and pause or switch-on changes in Google Ads have a one-step Undo (revertGroasActions, or Undo in the Groas dashboard). These do not:
- Creating a campaign or supercharging one: there is no earlier state to return to, and both can start spend. Stop either by pausing the campaign (set_status or the Groas dashboard).
- Removing a campaign or an ad group: Google Ads removes it for good, and its name stays taken. A removed keyword or ad can be put back, but the ad comes back as a new ad without its past results.
- Editing brand guidelines and offers: Claude gets the previous text back and can save it again, but there is no one-click Undo.
- Meta changes have no one-click Undo. The campaign's history in Groas records each one with what it was before, so it can be changed back by hand: a budget or bid set back, a paused ad set resumed. A new ad or ad set is stopped by pausing it (set_meta_status) or deleted in Meta Ads Manager.
Claude asks before changing anything. Write tools are marked destructive, so Claude confirms each call with you; read tools run without prompts.
Website changes. Published articles can be taken down again with revertArticle or from the Changes feed. A sent outreach email cannot be unsent.
Scope. The server only reaches the Google Ads accounts, Meta ad accounts and brands owned by your Groas account.
Rate limit. 600 requests per minute per credential.
Disconnecting. Remove the connector in Claude (Customize → Connectors) to discard its tokens, or delete the API key in Groas. Access tokens expire after one hour.
Data. Requests are processed by Groas under the Groas privacy policy. The server does not read your Claude conversations, memory or files; it only receives the tool calls Claude makes.

8. Troubleshooting

Symptom	Fix
"No Google Ads accounts are connected"	Connect one at Dashboard → Ad platforms and wait for the first sync to finish.
Write tools are missing or refused	The connection is read-only: you did not tick Also allow changes, the plan for that kind of change (paid ads or organic) is not active, or the key lacks the `write` scope. See section 6.
"Invalid or revoked API key"	The key was deleted or mistyped. Create a new one and update the header.
Sign-in window says the consent token expired	Start the connection again from the client; consent links are short-lived.
HTTP 429	Rate limit reached. Wait a minute or spread work across credentials.
Connector shows as "Custom" after an update	Remove it and add Groas again from the directory.

Still stuck? Email support@groas.ai with the client you are using and the exact error text.

← Back