# Meta Social MCP

A free, self-hosted [Model Context Protocol](https://modelcontextprotocol.io/) server
that lets Claude (or any MCP client) **publish and manage your organic Facebook Page and
Instagram content** directly through Meta's own Graph API — no paid third-party service
in the middle.

It complements an ads connector (e.g. Pipeboard's Meta Ads MCP): use the ads connector
for campaigns, and this one for organic posts, scheduling, comments and insights.

## What it can do

**Facebook Page**
- `facebook_publish_post` — publish a text, link, or photo post; schedule it for later
- `facebook_list_posts` — list recent published and scheduled posts
- `facebook_get_comments` — read comments on a post
- `facebook_reply_to_comment` — reply to a comment
- `facebook_get_insights` — post- or Page-level performance

**Instagram (Business/Creator)**
- `instagram_publish_photo` — single photo + caption
- `instagram_publish_carousel` — 2–10 image carousel
- `instagram_publish_reel` — video reel
- `instagram_publish_container` — publish a prepared container (retry reels / schedule)
- `instagram_list_media` — recent media
- `instagram_get_comments` — read comments
- `instagram_reply_to_comment` — reply to a comment
- `instagram_get_insights` — media- or account-level performance

**Utility**
- `meta_whoami` — confirm your token, Page and IG account resolve correctly

## Honest limitations (read these)

- **Facebook scheduling is native** (via `scheduled_publish_time`, 10 min–75 days ahead).
  **Instagram has no native scheduled-publish API** — to schedule IG posts you publish at
  the target time (e.g. an OS cron / external scheduler that calls the publish tool, or a
  container created earlier and published later with `instagram_publish_container`).
- **Instagram posting only works on a Business or Creator account linked to a Facebook
  Page.** Personal IG accounts cannot post via the API.
- **Images/videos must be at public URLs** — Instagram fetches media from a URL; it does
  not accept direct file uploads through this API.
- Going beyond your own assets / into production requires **Meta app review and business
  verification** for the publishing permissions.

## Prerequisites

1. A **Facebook Page** you manage.
2. For Instagram: an **Instagram Business/Creator account** linked to that Page.
3. A **Meta developer app** and an **access token** with these permissions:
   - `pages_show_list`
   - `pages_read_engagement`
   - `pages_manage_posts`
   - `pages_manage_engagement` (for replying to comments)
   - `read_insights`
   - `instagram_basic`
   - `instagram_content_publish`
   - `instagram_manage_comments` / `instagram_manage_insights` (for IG comments/insights)

### Getting a token (quick start for your own Page)

1. Go to <https://developers.facebook.com/apps> → **Create App** → type **Business**.
2. Add the **Facebook Login** and **Instagram Graph API** products.
3. Open the **Graph API Explorer** (<https://developers.facebook.com/tools/explorer>),
   select your app, and **Add permissions** for the scopes listed above.
4. **Generate Access Token** and approve the dialog. This gives a short-lived user token.
5. Exchange it for a **long-lived token** (≈60 days):
   ```
   https://graph.facebook.com/v21.0/oauth/access_token?grant_type=fb_exchange_token&client_id=APP_ID&client_secret=APP_SECRET&fb_exchange_token=SHORT_LIVED_TOKEN
   ```
6. Find your **Page ID**: open the Page → About, or call `GET /me/accounts`.
7. Find your **IG user ID**: `GET /{page-id}?fields=instagram_business_account`.

Put the long-lived user token in `META_ACCESS_TOKEN` — the server resolves the Page token
for you. (A Page token also works directly.)

## Install

```bash
git clone https://github.com/<your-username>/meta-social-mcp.git
cd meta-social-mcp
pip install -r requirements.txt        # or: pip install -e .
cp .env.example .env                   # then fill in your values
```

## Configure

Set these as environment variables or in `.env`:

| Variable            | Required | Description                                        |
|---------------------|----------|----------------------------------------------------|
| `META_ACCESS_TOKEN` | yes      | Long-lived user or Page access token               |
| `FB_PAGE_ID`        | yes*     | Facebook Page ID (*required for Facebook posting)  |
| `IG_USER_ID`        | no       | Instagram Business/Creator user ID                 |
| `GRAPH_API_VERSION` | no       | Defaults to `v21.0`                                |

## Run / connect to Claude

Add to your MCP client config (Claude Desktop `claude_desktop_config.json`, or the custom
connector settings). Example stdio config:

```json
{
  "mcpServers": {
    "meta-social": {
      "command": "python",
      "args": ["-m", "meta_social_mcp.server"],
      "cwd": "/absolute/path/to/meta-social-mcp",
      "env": {
        "META_ACCESS_TOKEN": "EAAB...",
        "FB_PAGE_ID": "1234567890",
        "IG_USER_ID": "1789xxxxxxxxxx",
        "GRAPH_API_VERSION": "v21.0"
      }
    }
  }
}
```

Then ask Claude things like:
- "Post to my Facebook Page: 'New off-market deal just listed', schedule it for tomorrow 9am."
- "Publish this image to Instagram with a caption about our latest project."
- "Show me the comments on my last Instagram post and draft replies."

## Verify it works

```bash
python -m py_compile meta_social_mcp/*.py     # syntax check
python -c "from meta_social_mcp.server import mcp; print('tools ok')"
```

Then in your client, run `meta_whoami` first — it confirms the token, Page and IG account
resolve before you try to post.

## License

MIT.