# Facebook Ads MCP Server

MCP server for Meta/Facebook Marketing API workflows.

It provides tools to:
- View ad accounts, campaigns, ad sets, ads, creatives, and activity history.
- Create and update campaigns, ad sets, ads, and creatives.
- Fetch insights at account/campaign/adset/ad level.
- Upload ad images (local file path only).

## Requirements

- Python 3.10+
- A Meta user access token with required scopes
- Access to at least one ad account

## Installation

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Authentication

The server supports either:
- CLI arg: `--fb-token <TOKEN>`
- Environment variable: `FACEBOOK_ACCESS_TOKEN` (or `FB_ACCESS_TOKEN`)

### Recommended local setup (`.env`)

```bash
cp .env.example .env
# then set FACEBOOK_ACCESS_TOKEN in .env
```

The server automatically loads `.env` via `python-dotenv`.

## Running Locally

```bash
python server.py --fb-token YOUR_META_ACCESS_TOKEN
```

or with `.env` configured:

```bash
python server.py
```

## MCP Client Configuration

Example:

```json
{
  "mcpServers": {
    "fb-ads-mcp-server": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "FACEBOOK_ACCESS_TOKEN": "YOUR_META_ACCESS_TOKEN"
      }
    }
  }
}
```

If your client does not support `env`, pass `--fb-token` in `args`.

## Tool Coverage

### Read/List
- `list_ad_accounts`
- `get_details_of_ad_account`
- `get_campaigns_by_adaccount`, `get_campaign_by_id`
- `get_adsets_by_adaccount`, `get_adsets_by_campaign`, `get_adsets_by_ids`, `get_adset_by_id`
- `get_ads_by_adaccount`, `get_ads_by_campaign`, `get_ads_by_adset`, `get_ad_by_id`
- `get_ad_creatives_by_ad_id`, `get_ad_creative_by_id`
- `get_activities_by_adaccount`, `get_activities_by_adset`

### Create/Update
- `create_campaign`, `update_campaign`
- `create_adset`, `update_adset`
- `create_ad`, `update_ad`
- `create_ad_creative`, `create_link_ad_creative`
- `upload_ad_image`

### Insights
- `get_adaccount_insights`
- `get_campaign_insights`
- `get_adset_insights`
- `get_ad_insights`
- `fetch_pagination_url`

## Important: `upload_ad_image` Is Local Path Only

`upload_ad_image` intentionally accepts only:
- `act_id`
- `image_path`
- optional `name`

It does **not** accept `image_url`.

Reason: URL ingestion through `/{ad_account_id}/adimages` is inconsistent across app/account capability states and commonly fails even when local upload works. Restricting this tool to local paths avoids ambiguous behavior.

Example:

```python
upload_ad_image(
    act_id="act_1234567890",
    image_path="/absolute/path/to/creative.png",
    name="creative_v1"
)
```

## Permissions and Access Checklist

Need the full end-to-end setup for Meta Business Center + App Dashboard?
See [docs/meta-business-center-setup.md](docs/meta-business-center-setup.md).

For most ad management/read workflows, ensure the token has:
- `ads_management`
- `ads_read`
- `business_management`

Page-related creative/ad flows may additionally need page scopes such as:
- `pages_show_list`
- `pages_read_engagement`
- `pages_manage_ads`

Operational requirements:
- The user tied to the token is added to the target ad account with sufficient role (typically Advertiser/Admin).
- The app is configured for Marketing API use case.
- In Development mode, only app roles/test users can use the app token flow.
- For non-role external users, required permissions/features must be approved for advanced access and app must be Live.

## Common Failure Modes

- `(#200) Permissions error`:
  - Missing permission scope on token, or user lacks ad account role.
- Empty ad account list:
  - User/token has no accessible ad accounts.
- `upload_ad_image` file error:
  - `image_path` is missing, relative to wrong runtime location, or file does not exist.

## Security Notes

- Never commit real tokens.
- `.env` is git-ignored; keep secrets there for local use.
- Rotate tokens if they were ever exposed.

## Development

Run a quick syntax check:

```bash
python3 -m py_compile server.py
```

## License

MIT