convez.ai
MCP ServerMarketing & VendasIntermediário
faiyazmn

Ad Analytics Workspace

faiyazmn/ad-analytics

Análise cross-channel de publicidade: Google, Meta e GA4 em uma interface natural

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP 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-analytics

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

ToolWhat it coversAccess
Google AdsCampaigns, keywords, search terms, spend, ROASRead only
Meta Ads (Facebook / Instagram)Campaigns, audiences, creative, spend, plus launching new adsRead and write
Google Analytics 4Sessions, traffic sources, conversions, funnelsRead only
HiggsfieldAI image and video generation for ad creativeCreates 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.

  1. 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.)

  2. Open it in Claude. Install the Claude desktop app (or the Claude Code CLI), then open this project folder as a new session.

  3. 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.

  4. 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 through pipx). 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 pipx is on your PATH (pipx ensurepath, then restart your shell) and that the credential paths in .claude/settings.local.json are 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 the env block in .claude/settings.local.json, then restart Claude Code (or run /mcp and 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_ID is the numeric ID, not the measurement ID (G-XXXX).
  • Meta will not connect: run /mcp again and complete the browser login; make sure your Meta user has access to the ad account.

License

MIT. See LICENSE. Contributions welcome.

Ver o original no GitHub

Bom para

Relacionados