# Meta Ads Insights MCP Server

A Model Context Protocol (MCP) server for accessing Meta (Facebook) Ads insights data with built-in support for joining with HubSpot deal data.

## Features

- Fetch ad insights with flexible filtering and breakdowns
- Campaign and ad set management
- Mobile placement tracking for revenue attribution
- Prepare ads data for joining with HubSpot deals
- Configurable access tokens via MCP configuration

## Setup

1. **Install dependencies:**
```bash
npm install
```

2. **Build the server:**
```bash
npm run build
```

3. **Configure Claude Desktop:**
Add the server configuration to your Claude Desktop config file:

**Location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

**Configuration:**
```json
{
  "mcpServers": {
    "meta-ads-insights": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/dist/index.js"],
      "env": {
        "META_ACCESS_TOKEN": "your_meta_access_token_here",
        "META_AD_ACCOUNT_ID": "your_ad_account_id_without_act_prefix",
        "META_API_VERSION": "v19.0"
      }
    }
  }
}
```

4. **Get your Meta Access Token:**
   - Go to [Meta for Developers](https://developers.facebook.com/)
   - Create an app or use existing app
   - Generate a User Access Token with `ads_read` permission
   - For production, use a System User Access Token

5. **Find your Ad Account ID:**
   - Go to Meta Ads Manager
   - The account ID is in the URL: `act_1234567890` (use just `1234567890`)

## Available Tools

### `get_ad_insights`
Fetch ad performance data with breakdowns and filtering.

**Example usage:**
```
Get mobile ad performance for the last 30 days with placement breakdown
```

### `get_campaigns`
List campaigns with filtering options.

### `get_adsets` 
List ad sets, optionally filtered by campaign.

### `prepare_hubspot_join`
Prepare ads data for joining with HubSpot deals data using various strategies:
- **date_range**: Match deals created within attribution window
- **utm_params**: Match deals with UTM parameters
- **conversion_tracking**: Match deals with Facebook click IDs

**Example workflow:**
1. Get mobile placement ads data
2. Prepare for HubSpot join with date range strategy
3. Use the prepared data to query HubSpot for deals created within the attribution window
4. Analyze mobile ads → revenue correlation

## Example Use Cases

### Mobile Ads Revenue Attribution
```
1. Get ads insights with device_platform and placement breakdowns
2. Filter for mobile placements
3. Prepare data for HubSpot join with 7-day attribution window
4. Query HubSpot deals created in that timeframe
5. Calculate ROI from mobile ad spend to deal revenue
```

### Campaign Performance Analysis
```
1. Get campaign insights for last 30 days
2. Break down by placement and device
3. Join with HubSpot deal data
4. Identify highest-converting campaign + placement combinations
```

## Data Joining Strategy

The server provides a `prepare_hubspot_join` tool that:
- Adds join keys based on strategy (UTM params, date ranges, click IDs)
- Calculates attribution windows
- Flags mobile placements for filtering
- Provides HubSpot query suggestions

This allows you to connect ad performance data with actual revenue outcomes tracked in HubSpot.

## Development

```bash
# Development mode with auto-rebuild
npm run dev

# Build only
npm run build

# Run built server
npm start
```

## Troubleshooting

- Ensure your Meta access token has `ads_read` permission
- Verify the ad account ID is correct (without "act_" prefix)
- Check that the absolute path in claude_desktop_config.json is correct
- Restart Claude Desktop after configuration changes# meta-insights-mcp