# Marketing Analytics MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server that gives an
LLM **live, read-only access to a marketing analytics stack** — so you can ask
questions in natural language instead of jumping between dashboards. Exposes tools
across Google Search Console, GA4, Google Ads, HubSpot CRM, and Bing Webmaster
Tools, plus composite cross-platform rollups.

Runs locally over stdio (Claude Desktop / Claude Code) or as a remote
streamable-HTTP service (e.g. Cloud Run) with bearer-token auth.

## Tools

| Area | Examples |
|---|---|
| **Search Console** | queries, pages, CTR/position, period comparison, movers & losers |
| **GA4** | sessions, channels, landing pages by source, funnels, conversions |
| **Google Ads** | campaign performance, keyword quality, search terms |
| **HubSpot** | deal / company / contact search, pipeline summary, activity timelines |
| **Bing** | top queries/pages, branded vs unbranded, crawl stats |
| **Composite** | cross-platform marketing snapshot |

## Design

- `clients/` — one thin async client per platform (auth + raw calls).
- `tools/` — MCP tool definitions that shape client output for an LLM.
- `cache.py` — TTL cache to stay inside free-tier API limits.
- `circuit_breaker.py` — trips on repeated upstream failures so one bad provider can't hang the server.
- `server.py` — registers tools and serves stdio or streamable-HTTP.

## Setup

```bash
pip install -e .
cp .env.example .env     # fill in your own credentials + property IDs
python -m mcp_server.server
```

All credentials and property/account IDs come from environment variables (see
`.env.example`) — nothing is hardcoded. You point it at **your own** analytics
accounts.

### Deploy (remote)

A `Dockerfile` + `Procfile` are included. Set `MCP_AUTH_TOKEN` so only requests
carrying the bearer token can connect, then deploy to any container host.

## Tests

```bash
pytest
```