# AdPage MCP Server

AdPage MCP Server provides real-time access to server-side tracking data, marketing attribution, conversion funnels, ad platform performance, and more — all through the Model Context Protocol (MCP).

## Features

- **Marketing Attribution** — First-click and last-click attribution models showing which channels drive revenue
- **Conversion Funnel** — E-commerce funnel analysis from page view to purchase
- **Revenue Reporting** — Daily revenue trends with transaction counts and average order value
- **Platform Health** — Real-time status of tracking platforms (GA4, Meta, TikTok, etc.)
- **Data Quality** — Coverage and completeness metrics for tracking data
- **Google Ads** — Campaign performance, ROAS, ad group metrics, search term reports
- **Meta/Facebook Ads** — Campaign insights with demographic and platform breakdowns
- **TikTok Ads** — Campaign performance, conversions, and ROAS
- **LinkedIn Ads** — Campaign analytics, spend, CTR, and CPC
- **Google Analytics 4** — Sessions, users, events, conversions, and real-time data
- **Custom Queries** — Execute custom ClickHouse SQL on tracking data

## Setup

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "adpage": {
      "url": "https://app.adpage.io/api/mcp-external/YOUR_TOKEN"
    }
  }
}
```

### Claude Code

Add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "adpage": {
      "type": "url",
      "url": "https://app.adpage.io/api/mcp-external/YOUR_TOKEN"
    }
  }
}
```

### Other MCP-compatible tools

Use the Streamable HTTP transport:

- **Endpoint:** `POST https://app.adpage.io/api/mcp-external/YOUR_TOKEN`
- **Protocol:** MCP 2024-11-05 via JSON-RPC 2.0
- **Headers:** `Content-Type: application/json`, `Accept: application/json, text/event-stream`
- **Session:** send `initialize` first and pass the `Mcp-Session-Id` it returns on every later request. `tools/call` without a valid session is rejected (HTTP 404 for an expired or unknown session: initialize again).

## Authentication

Token-based authentication. Your MCP token is embedded in the URL path. Get your token from the AdPage dashboard at Settings > MCP Connection.

Tokens are scoped to your user account and provide access to all containers you own or have access to through your agency. A tool called with a `container_id` outside that set is refused, and `list_containers` only lists that set.

## Tools

### Tracking Data (14 tools)

| Tool | Description |
|------|-------------|
| `get_attribution` | Marketing attribution (first/last click) with revenue per channel |
| `get_funnel` | E-commerce conversion funnel (page_view → purchase) |
| `get_revenue` | Daily revenue trends, transactions, avg order value |
| `get_platform_health` | Status per tracking platform with success rates |
| `get_data_quality` | Data coverage and completeness percentages |
| `execute_query` | Custom ClickHouse SQL queries on tracking data |
| `list_containers` | List all containers with recent activity |
| `search_containers` | Search containers by name or domain |
| `query_google_ads` | Google Ads campaign performance via GAQL |
| `query_facebook_ads` | Meta/Facebook Ads insights with breakdowns |
| `query_tiktok_ads` | TikTok Ads campaign performance |
| `query_linkedin_ads` | LinkedIn Ads campaign analytics |
| `query_google_analytics` | GA4 reports and real-time data |
| `get_integration_status` | Check which ad platforms are connected |

All tools are **read-only** and never modify your data.

## Examples

### Example 1: Marketing Attribution Analysis

**User:** "Which marketing channel drives the most revenue?"

**Claude uses:** `get_attribution` with `model: "last_click"`, `days: 30`

**Result:** Returns a table showing source/medium pairs ranked by revenue, with conversion counts and average order values.

---

### Example 2: Conversion Funnel Analysis

**User:** "Show me the conversion funnel for my webshop"

**Claude uses:** `get_funnel` with `days: 30`

**Result:** Returns funnel steps (page_view → view_item → add_to_cart → begin_checkout → purchase) with event counts and unique sessions per step.

---

### Example 3: Google Ads Performance

**User:** "How much did I spend on Google Ads last month and what's the ROAS?"

**Claude uses:** `query_google_ads` with `query_type: "campaign_performance"`, `date_range: "LAST_30_DAYS"`

**Result:** Returns campaign-level data with spend, clicks, impressions, conversions, conversion value, and calculated ROAS.

---

### Example 4: Cross-Platform Comparison

**User:** "Compare Facebook Ads vs Google Ads performance this month"

**Claude uses:** `query_facebook_ads` + `query_google_ads` with matching date ranges

**Result:** Returns campaign data from both platforms, enabling side-by-side comparison of spend, conversions, and ROAS.

---

### Example 5: Platform Health Check

**User:** "Are all tracking platforms healthy?"

**Claude uses:** `get_platform_health` with `days: 7`

**Result:** Returns per-platform success rates showing total requests, successful deliveries, failures, and percentage success rate.

---

### Example 6: Daily Revenue Trends

**User:** "What's my daily revenue trend this month?"

**Claude uses:** `get_revenue` with `days: 30`

**Result:** Returns daily revenue in EUR, transaction count, and average order value for trend analysis. Orders in another currency are converted at the ECB reference rate of the order date; the `fx` object lists what was converted, which orders carried no currency (counted as EUR) and which were left out because no rate exists.

---

### Example 7: TikTok Ads Campaign Performance

**User:** "Show TikTok Ads campaign performance this week"

**Claude uses:** `query_tiktok_ads` with `query_type: "campaign_insights"`, last 7 days

**Result:** Returns campaign-level spend, impressions, clicks, conversions, and ROAS from TikTok Ads.

---

### Example 8: Integration Status Check

**User:** "Which ad platforms are connected to my container?"

**Claude uses:** `get_integration_status`

**Result:** Returns connection status for Google Ads, Facebook Ads, TikTok Ads, LinkedIn Ads, and GA4.

## Privacy Policy

AdPage MCP Server processes data in accordance with AdPage's privacy policy.

- **Data collected:** Server-side tracking events, container metadata, ad platform metrics (via user-authorized OAuth connections)
- **Data usage:** Read-only queries for analytics and reporting purposes only
- **Data storage:** All data remains in AdPage's infrastructure (ClickHouse database). Ad platform data is fetched in real-time from the respective APIs and not stored
- **Third-party sharing:** No data is shared with third parties
- **Data retention:** Tracking data follows AdPage's standard retention policy
- **Contact:** support@adpage.io

Full privacy policy: https://adpage.io/privacy

## Support

- **Email:** support@adpage.io
- **Website:** https://adpage.io
- **Documentation:** https://app.adpage.io/mcp-docs/README.md
