# facebook-mcp

MCP server for **organic Facebook Page** analytics via the Meta Graph API
(no Ads API). The Instagram tools live in the separate `instagram-mcp` server.

Connects every Facebook Page you manage; tools default to your first Page and
accept `page_id` to target another.

## Quick start

```bash
# Windows: double-click start.bat   ·   macOS/Linux: ./start.sh   ·   or:
python launcher.py
```

Installs deps, logs in with Facebook (saving tokens), and registers `facebook`
in your Claude Desktop config. You need a Meta App ID + Secret (one-time app with
Facebook Login and redirect URI `http://localhost:8765/callback`).

## Tools

- `list_connected_accounts`, `fb_get_all_pages_posts`, `fb_get_all_pages_summary`
- `fb_get_page_posts`, `fb_get_post_insights`, `fb_get_page_insights`
- `fb_get_page_profile`, `fb_get_page_videos`, `fb_get_page_audience`
- `fb_get_post_comments`, `fb_get_top_posts`
- `fb_get_follower_growth`, `fb_get_engagement_rate`, `fb_compare_page_insights`
- `account_health_report`, `list_available_metrics`
- Resource `facebook://pages`
- Publishing (opt-in): `fb_publish_post`, `fb_reply_comment`, `fb_hide_comment`, `fb_delete_comment`

All tools take `response_format` (markdown default / json). Insight tools accept
`date_preset` (last_7d, last_30d, this_month, …).

## Auth & credentials

Login is shared with `instagram-mcp` — both read the same
`~/.config/meta-social-mcp/credentials.json`, so logging in from either server
sets up both. Read permissions: `pages_show_list`, `pages_read_engagement`,
`read_insights`, `business_management`.

```bash
python server.py login --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET
python server.py whoami
```

Publishing requires `--with-publishing` at login (adds `pages_manage_posts`,
`pages_manage_engagement`; needs Meta App Review) and `META_ENABLE_PUBLISHING=1`.

## Env knobs

`META_GRAPH_VERSION` (default v19.0), `META_CACHE_TTL`, `META_ENABLE_PUBLISHING`,
`META_PAGE_ACCESS_TOKEN`, `FB_PAGE_ID`, `META_SOCIAL_CREDENTIALS`.