Metadata-Version: 2.3
Name: meta-ads-mcp-python
Version: 1.0.80
Summary: MCP server for Meta Ads API -- manage campaigns, ad sets, ads, and Business Manager accounts
Keywords: meta,facebook,ads,api,mcp,claude
Author: Yves Junqueira
Author-email: Yves Junqueira <yves.junqueira@gmail.com>
License: BUSL-1.1
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: pydantic>=2.11.7
Requires-Dist: pydantic-settings>=2.10.1
Requires-Dist: httpx>=0.26.0
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: requests>=2.32.3
Requires-Dist: pillow>=10.0.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/locomotive-agency/meta-ads-mcp-python
Project-URL: Bug Tracker, https://github.com/locomotive-agency/meta-ads-mcp-python/issues
Description-Content-Type: text/markdown

# Meta Ads MCP

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for analysing Meta Ads campaigns through an AI interface. Retrieve performance data, visualize ad creatives, and surface insights for Facebook, Instagram, and other Meta platforms.

> **Read-only:** All tools are strictly read-only. No tool creates, modifies, or deletes any data.

> **Independent project:** This is an open-source project using Meta's public APIs. Not affiliated with or endorsed by Meta. For an officially approved Meta app, see [Pipeboard](https://pipeboard.co).

---

## Quick Start (Remote MCP)

The fastest way to get started is the [Pipeboard remote MCP](https://pipeboard.co) — no local setup required.

Remote MCP URL: `https://mcp.pipeboard.co/meta-ads-mcp`

With token auth: `https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN`

Get your token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens).

### Claude (Pro/Max)

1. Go to [claude.ai/settings/integrations](https://claude.ai/settings/integrations)
2. Click **Add Integration**, set the URL to `https://mcp.pipeboard.co/meta-ads-mcp`
3. Click **Connect** and follow the prompts.

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "meta-ads-remote": {
      "url": "https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN"
    }
  }
}
```

### Other MCP Clients

Use the remote URL above. Full setup guides: [pipeboard.co](https://pipeboard.co)

---

## Local Installation

> For advanced users. The remote MCP is recommended for most cases.

**Requirements:** Python 3.12+, a Meta Developer App (App ID + Secret), and [uv](https://github.com/astral-sh/uv).

```bash
pip install meta-ads-mcp
```

### Authentication

Copy `.env.example` to `.env` and set one of:

```
PIPEBOARD_API_TOKEN=your_token       # Recommended — no Meta app required
META_APP_ID=your_app_id              # Direct Meta app credentials
META_APP_SECRET=your_app_secret
```

### Run

```bash
meta-ads-mcp                         # stdio (default)
python -m meta_ads_mcp --transport streamable-http --host localhost --port 8080  # HTTP
```

### Claude Desktop config

```json
{
  "mcpServers": {
    "meta-ads": {
      "command": "meta-ads-mcp"
    }
  }
}
```

---

## Configuration

| Variable | Description |
|---|---|
| `PIPEBOARD_API_TOKEN` | Pipeboard API token (recommended) |
| `META_APP_ID` | Meta Developer App ID (direct auth) |
| `META_APP_SECRET` | Meta Developer App Secret (direct auth) |
| `LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`) |
| `SERVER_HOST` | HTTP transport host (default: `localhost`) |
| `SERVER_PORT` | HTTP transport port (default: `8080`) |

---

## Available Tools

| Tool | Description |
|---|---|
| `mcp_meta_ads_get_ad_accounts` | List accessible ad accounts |
| `mcp_meta_ads_get_account_info` | Get details for a specific ad account |
| `mcp_meta_ads_get_account_pages` | Get pages associated with an ad account |
| `mcp_meta_ads_get_campaigns` | List campaigns with optional status filter |
| `mcp_meta_ads_get_campaign_details` | Get details for a specific campaign |
| `mcp_meta_ads_get_adsets` | List ad sets, optionally filtered by campaign |
| `mcp_meta_ads_get_adset_details` | Get details for a specific ad set |
| `mcp_meta_ads_get_ads` | List ads, optionally filtered by campaign or ad set |
| `mcp_meta_ads_get_ad_details` | Get details for a specific ad |
| `mcp_meta_ads_get_ad_creatives` | Get creative details (text, images, URLs) |
| `mcp_meta_ads_get_ad_image` | Download and visualize an ad image |
| `mcp_meta_ads_get_insights` | Get performance metrics with attribution windows and breakdowns |
| `mcp_meta_ads_get_login_link` | Get a login link for Meta authentication |
| `mcp_meta_ads_search_interests` | Search interest targeting options by keyword |
| `mcp_meta_ads_get_interest_suggestions` | Get interest suggestions based on existing interests |
| `mcp_meta_ads_validate_interests` | Validate interest names or IDs |
| `mcp_meta_ads_search_behaviors` | List available behavior targeting options |
| `mcp_meta_ads_search_demographics` | List demographic targeting options |
| `mcp_meta_ads_search_geo_locations` | Search geographic targeting locations |
| `mcp_meta_ads_search` | Generic search across accounts, campaigns, ads, and pages |
| `mcp_meta_ads_get_businesses` | List all Business Manager accounts |
| `mcp_meta_ads_get_business_ad_accounts` | List ad accounts under a Business Manager |
| `mcp_meta_ads_find_client_account` | Search for a client account across Business Managers |
| `mcp_meta_ads_get_business_details` | Get details for a specific Business Manager |

---

## Troubleshooting

- **Auth errors:** Check your token/credentials in `.env`. Use `mcp_meta_ads_get_login_link` to re-authenticate.
- **No accounts returned:** Ensure the user has access to at least one ad account in Meta Business Manager.
- **Tool not found:** Confirm the server is running and your client config is correct.

---

## Privacy and Security

- Remote MCP: auth is handled in the cloud, no tokens stored locally.
- Local install: tokens are cached on your machine. Never commit your `.env` file.
- The server never exposes your access token to the LLM.

---

## Licensing

Licensed under the [Business Source License 1.1](LICENSE). Free for individual and business use. Converts to Apache 2.0 on January 1, 2029. You may not offer this as a competing hosted service.

For commercial licensing: [info@pipeboard.co](mailto:info@pipeboard.co)

---

## Support

- [Discord](https://discord.gg/YzMwQ8zrjr)
- [GitHub Issues](https://github.com/pipeboard-co/meta-ads-mcp/issues)
- [Email](mailto:info@pipeboard.co)
