meta-ads-mcp

# Meta Ads MCP Server A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes Meta Ads data to Claude (Desktop or Code). ## Tools available | Tool | Description | |---|---| | `get_ad_accounts` | List all accessible ad accounts | | `get_account_info` | Detailed info for a specific account | | `get_campaigns` | List campaigns with optional status filter | | `get_adsets` | List ad sets | | `get_ads` | List individual ads | | `get_account_insights` | Account-level metrics | | `get_campaign_insights` | Campaign-level metrics with sorting & breakdown | | `get_adset_insights` | Ad set level metrics | | `get_ad_insights` | Ad level metrics | | `get_insights_by_time` | Time-series data for trend analysis | ## Requirements - Python 3.10+ - A Meta [System User token](https://www.facebook.com/business/help/503306463479099) with `ads_read` permission ## Setup ### 1. Clone and install ```bash git clone https://github.com/your-user/meta-ads-mcp cd meta-ads-mcp python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt ``` ### 2. Configure credentials ```bash cp .env.example .env ``` Edit `.env` and fill in your values: ```env META_APP_ID="your_app_id" META_APP_SECRET="your_app_secret" META_GRAPH_VERSION="v21.0" META_SYSTEM_USER_TOKEN="your_system_user_token" ``` ### 3. Add to Claude Desktop Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { "mcpServers": { "meta-ads": { "command": "/absolute/path/to/.venv/bin/python", "args": ["/absolute/path/to/server.py"] } } } ``` Restart Claude Desktop. The 🔨 icon will show the available tools. ### 4. Add to Claude Code ```bash claude mcp add meta-ads /absolute/path/to/.venv/bin/python -- /absolute/path/to/server.py ``` ## Usage examples Once connected, ask Claude naturally: - *"Show me all my Meta ad accounts"* - *"What are my active campaigns?"* - *"Give me campaign metrics for the last 7 days"* - *"Show spend and ROAS broken down by country"* - *"Daily performance trend for this month"* ## Getting a System User Token 1. Go to [Meta Business Manager](https://business.facebook.com) 2. Settings → Users → **System Users** 3. Create or select a System User 4. Click **Generate Token** → select your app → enable `ads_read` 5. Copy the token into your `.env` ## License MIT