# Jarvis: marketing MCP server for Claude

One self-hosted [MCP](https://modelcontextprotocol.io) server that gives Claude read **and write** access to your
marketing stack: about 216 tools across Google Ads, Meta Ads, GA4, Google Search Console and Microsoft Clarity.

Use it locally from Claude Code or Claude Desktop, or host it and add it to claude.ai as a custom connector,
so it also works in the Claude mobile app and in Cowork.

## What's inside

| Prefix | Platform | Tools | Highlights |
|---|---|---|---|
| `gads_` | Google Ads | ~114 | Account and campaign reporting, search terms, keywords, negatives, bids, budgets, Search/PMax/Display/Demand Gen campaign builders, ads and extensions, experiments, labels, conversions, Customer Match (via the Data Manager API), raw GAQL and raw mutate |
| `meta_` | Meta (Facebook/Instagram) Ads | ~81 | Insights with breakdowns, creative fatigue, campaigns/ad sets/ads/creatives, audiences (website, engagement, lookalike, customer list), lead forms and leads, Page posts and insights, boosting, catalogs, automated rules, raw Graph API |
| `google_` | GA4, Search Console, Clarity | ~21 | AI-assistant referral traffic (ChatGPT, Perplexity, Gemini, ...), pivot and batch reports, GA4 admin reads, search queries and pages, keyword opportunities, period comparisons, URL inspection, indexation summary, sitemaps, Clarity UX insights |

### Safety: every change is preview-first
Every tool that changes an account takes `confirm=false` by default. That call changes nothing: it asks the
platform to validate the change (Google Ads `validate_only`, Meta `execution_options=validate_only`) and returns
a preview. Claude is instructed to show you the preview and only call again with `confirm=true` after you approve.
New Meta campaigns, ad sets and ads are created paused.

## Setup

Requires Python 3.11+.

```bash
git clone https://github.com/cgerig/jarvis-marketing-mcp.git
cd jarvis-marketing-mcp
python -m venv .venv && .venv/bin/pip install -r requirements.txt
cp .env.example .env   # then fill it in
```

### Credentials
You only need the platforms you use; tools for a platform without credentials return a readable error.

- **Google (Ads, GA4, Search Console, Customer Match):** sign in with Application Default Credentials:
  ```bash
  gcloud auth application-default login --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/webmasters,https://www.googleapis.com/auth/datamanager,https://www.googleapis.com/auth/cloud-platform
  ```
  Google Ads also needs a [developer token](https://developers.google.com/google-ads/api/docs/get-started/dev-token).
  Enable the Google Ads, Analytics Data, Analytics Admin, Search Console and Data Manager APIs on your Cloud project.
- **Meta:** a System User access token (Business Settings > Users > System users) with `ads_management`,
  `ads_read`, `business_management`, `leads_retrieval`, `pages_show_list`, `pages_read_engagement`,
  `pages_manage_ads` and `read_insights`.
- **Clarity:** Settings > Data Export > Generate new API token (Clarity allows 10 export calls a day).

## Use it

### Locally (Claude Code or Claude Desktop)
Runs over stdio, so nothing is exposed to the network:
```bash
claude mcp add jarvis --scope user -- /path/to/jarvis-marketing-mcp/run_stdio.sh
```

### As a remote connector (claude.ai, mobile, Cowork)
`connector/app.py` serves everything over Streamable HTTP at `/mcp`, protected by GitHub sign-in that only lets
in the usernames in `ALLOWED_GITHUB_USERS`.

1. Pick a public HTTPS address: a host such as Cloud Run, Render or Fly.io (use the `Dockerfile`), or your own
   computer behind [Tailscale Funnel](https://tailscale.com/kb/1223/funnel) or Cloudflare Tunnel.
2. Create a [GitHub OAuth App](https://github.com/settings/applications/new) with callback URL
   `https://YOUR-ADDRESS/auth/callback`.
3. Set the `PUBLIC_URL`, `GITHUB_*`, `ALLOWED_GITHUB_USERS` and `JWT_SIGNING_KEY` settings (see `.env.example`),
   and point `OAUTH_STORE_DIR` at persistent storage so sign-ins survive restarts.
4. Start it with `./run_http.sh`, or deploy the Docker image.
5. In claude.ai: **Settings > Connectors > Add custom connector**, URL `https://YOUR-ADDRESS/mcp`.

Keep secrets in `.env` or your host's secret manager; `.gitignore` already excludes them.

## Project layout
```
connector/app.py      combined server: mounts the three tool sets, sign-in, stdio or http
google/gads_tools/    Google Ads tools
google/gx_tools/      GA4 extras, Search Console, Clarity
meta/meta_tools/      Meta Ads tools
```

## License
MIT