Ad Analytics Workspace
faiyazmn/ad-analytics
Análise cross-channel de publicidade: Google, Meta e GA4 em uma interface natural
Ver no GitHubMCP server que conecta Google Ads, Meta Ads e Google Analytics 4 ao Claude para análise unificada de campanhas publicitárias. Permite consultas em linguagem natural sobre desempenho de anúncios, gera relatórios semanais automatizados e lança novas campanhas Meta com criatividade gerada por IA.
Instalação
npx convez-ai faiyazmn/ad-analytics1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Comparar desempenho e ROI entre Google Ads e Meta Ads
- Correlacionar gastos em publicidade com conversões no site via GA4
- Gerar relatórios semanais automáticos de desempenho de campanhas
- Lançar novas campanhas Meta com criatividade gerada por IA
Veredito

Ferramenta sólida para marketers que precisam de visão unificada de campanhas multi-canal. A capacidade de joinar dados de Google, Meta e GA4 resolve um problema real. Requer acesso a APIs das plataformas, mas setup é acessível mesmo para não-devs.
README
A tradução para o português deste README ainda está na fila.
Ad Analytics Workspace
Connect your Google Ads, Meta Ads, and Google Analytics 4 accounts to Claude, then ask plain-English questions about your advertising. Claude does the analysis, writes the reports, and can even build new Meta ads for you (with AI-generated creative).
Built for marketers and business owners. If you can gather a few account logins and paste an API token, you can run this. Claude walks you through the rest.
"How did our Google and Meta spend compare last week, and which channel actually drove more leads on the site?"
Ask that in everyday language and get a real answer that ties ad spend to on-site results.
What it does
Your ad data lives in separate silos: Google Ads and Meta Ads each report their own clicks and cost, while Google Analytics 4 (GA4) reports what visitors did on your website. The question that matters, "what did our ad spend actually do for the business?", sits in the join between them.
This workspace connects all of it to Claude and closes that gap. You ask questions in plain English; Claude pulls the numbers from each platform, joins paid spend to on-site conversions, and tells you what to scale, cut, or fix.
What you can do with it
- Ask anything in plain English. No dashboards or query languages. "Show me last month's Meta ad sets by cost per lead." "Which landing pages convert best for paid search?"
- See the full picture. Claude joins what you spent (Google and Meta) to what happened on your site (GA4), and flags when the platforms' numbers disagree with GA4 and why.
- Get automated weekly reports. A one-line setup runs a full cross-channel report every Monday for the prior week, written to a file. (Read-only, so it can never change your campaigns.)
- Launch new Meta ads with AI creative. Describe an offer; Claude generates the image or video with Higgsfield, builds the Meta campaign paused, shows you a preview, and goes live only when you explicitly approve.
- Reuse it for any business. Nothing business-specific is committed. Add your own accounts and context and it works for you.
The connected tools
| Tool | What it covers | Access |
|---|---|---|
| Google Ads | Campaigns, keywords, search terms, spend, ROAS | Read only |
| Meta Ads (Facebook / Instagram) | Campaigns, audiences, creative, spend, plus launching new ads | Read and write |
| Google Analytics 4 | Sessions, traffic sources, conversions, funnels | Read only |
| Higgsfield | AI image and video generation for ad creative | Creates assets (uses credits) |
Each analytics channel has a dedicated specialist that Claude hands questions to, so answers stay focused and accurate.
Two ways to use it
A. Start here (no coding required)
You do not need to be a developer. The idea is simple: put this project on your computer, open it in Claude, and let Claude guide you through the rest.
-
Get the project. On the GitHub page, click Use this template if you see it (or Fork, or Code > Download ZIP), then put it on your computer. (Or ask a colleague to clone it for you.)
-
Open it in Claude. Install the Claude desktop app (or the Claude Code CLI), then open this project folder as a new session.
-
Paste this first message and send it:
Read README.md and CLAUDE.md, then walk me through setting this workspace up step by step. Start by telling me exactly which accounts and credentials I need to gather and where to get each one. Go one step at a time and wait for me.
Claude will tell you which logins and tokens to collect, help you put them in the right places, and confirm each connection. You provide the account access; Claude handles the wiring.
-
Then just ask. Once connected, talk to it like a marketing analyst:
- "What did we spend on Google vs Meta last week, and which drove more leads?"
- "Generate a cross-channel report for last month."
- "Launch a Meta ad for our spring service special."
B. For developers (fork and customize)
Clone it, drop in your credentials, and customize freely: edit the specialist agents in
.claude/agents/, change the report layout in reports/templates/, adjust the launch flow in
.claude/commands/launch-meta-ad.md, or wire in additional channels. Config lives in
.mcp.json (committed, using ${ENV} placeholders); real secrets live in gitignored files.
Setup (the credentials Claude will help you gather)
You can do this yourself, or paste the first message above and let Claude lead you through it.
Prerequisites
- Claude Code (desktop app or CLI).
- Python 3.10+ and
pipx(the two Google servers run locally throughpipx). On macOS:brew install pipx && pipx ensurepath. - A Google Cloud project with three APIs enabled: Google Ads API, Google Analytics Admin API, Google Analytics Data API.
- A Meta Business account with access to the ad account you want to use.
- (Optional) A Higgsfield account, only if you want to generate creative or launch Meta ads. It connects with a browser login on first use (free tier is about 150 credits/month).
1. Create your local files
cp .claude/settings.local.json.example .claude/settings.local.json
cp company-knowledge.example.md company-knowledge.md
Both files are gitignored, so your secrets and business details never get committed. One
important note: Claude Code reads these values from .claude/settings.local.json, not from a
.env file. It does not load .env files at all, so don't put credentials there expecting
the servers to find them.
2. Gather your credentials
Google Cloud: in the Google Cloud Console, pick or create a project, note its Project ID, and enable the three APIs listed above.
GA4: create a service account in that project, download its JSON key, and save it as
credentials/ga4-service-account.json. In GA4 Admin, Property Access Management, add the
service account's email as a Viewer. Note your numeric GA4 Property ID (Admin,
Property Settings).
Google Ads: in your Google Ads account, open Tools and Settings, API Center and get
your developer token. Provide a credential authorized for the account (simplest:
gcloud auth application-default login, then point GOOGLE_ADS_CREDENTIALS at the resulting
file). Note your manager (MCC) account ID if you use one.
Meta Ads: nothing to download. Meta's hosted server uses a browser login the first time you use it.
3. Fill in .claude/settings.local.json
{
"env": {
"GOOGLE_PROJECT_ID": "your-gcp-project-id",
"GA4_CREDENTIALS": "/absolute/path/to/credentials/ga4-service-account.json",
"GA4_PROPERTY_ID": "123456789",
"GOOGLE_ADS_CREDENTIALS": "/absolute/path/to/credentials/google-ads.json",
"GOOGLE_ADS_DEVELOPER_TOKEN": "your-developer-token",
"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890"
}
}
Use absolute paths for the two credential files. GOOGLE_ADS_LOGIN_CUSTOMER_ID is your
manager (MCC) account ID, digits only; use an empty string if you don't have one. Claude
Code applies this env block to the session and expands the matching ${...} placeholders
in .mcp.json when the MCP servers start, so no secret ever lives in a committed file. If
you change these values while Claude is open, restart Claude Code (or run /mcp and
reconnect) so the servers pick them up.
4. Fill in company-knowledge.md
Replace the placeholders with your business: overview, locations, your Google Ads / Meta / GA4 account IDs, your conversion definitions, and KPI targets. The specialists read this file to know which accounts to query and what "good" looks like for you.
5. Connect and authenticate
Open the project in Claude, run /mcp, and confirm google-ads, ga4, and meta-ads
connect. The first time, meta-ads (and higgsfield, if you use it) will open a browser
login. Grant access and you are ready.
Using it
Just ask in natural language. Some examples:
- "Show me last 30 days of Google Ads spend and cost per lead by campaign."
- "Which Meta ad sets have the best cost per result this month?"
- "In GA4, what were last week's conversions by channel and top landing pages?"
- "Compare Google vs Meta spend and leads for May, and tell me which to scale."
Generate a cross-channel report
"Generate a cross-channel report for last month."
Claude gathers data from all three channels, fills the template in reports/templates/, and
saves a finished report to reports/output/.
Launch a new Meta ad
"/launch-meta-ad a spring service special for new customers"
The /launch-meta-ad command runs the whole flow: it collects the brief (objective, audience,
budget, copy), generates creative with Higgsfield, builds the Meta campaign all paused,
shows you a preview, and activates it only after you explicitly say to go live. Creative
generation uses Higgsfield credits and a live campaign spends real money, so it confirms at
every step.
Automated weekly report
scripts/weekly-report.sh runs the cross-channel report by itself
for the previous full week, compared to the week before, and saves it to reports/output/.
It is locked to read-only tools, so it can never touch a live campaign. Run it once to try
it:
./scripts/weekly-report.sh
To run it automatically every Monday at 08:00 on macOS, install the launchd job; setup
instructions are in
scripts/com.adanalytics.weekly-report.plist.example.
On Linux (or anywhere cron runs), use a crontab entry instead:
0 8 * * 1 cd /absolute/path/to/ad-analytics && ./scripts/weekly-report.sh
A note on safety and spend
- Google Ads and GA4 are read-only here. Neither can change anything. If you need a Google Ads change, make it in the Google Ads interface.
- Only Meta can change live campaigns, and only with your explicit confirmation. New campaigns are always created paused, and nothing goes live without a separate approval from you.
- Creative generation costs credits and live ads spend money. Claude confirms before any action that costs either.
Troubleshooting
- A Google server will not start: make sure
pipxis on yourPATH(pipx ensurepath, then restart your shell) and that the credential paths in.claude/settings.local.jsonare absolute. - A Google tool fails with an error containing literal
${GA4_CREDENTIALS}or${GOOGLE_ADS_CREDENTIALS}text: the environment values were not applied when the server started. Check theenvblock in.claude/settings.local.json, then restart Claude Code (or run/mcpand reconnect). - Google Ads auth errors: confirm the developer token is approved and the credential has
access to the customer ID in
company-knowledge.md. - GA4 returns no data or a 403: confirm the service account is a Viewer on the property and
that
GA4_PROPERTY_IDis the numeric ID, not the measurement ID (G-XXXX). - Meta will not connect: run
/mcpagain and complete the browser login; make sure your Meta user has access to the ad account.
License
MIT. See LICENSE. Contributions welcome.