# facebook-automata-mcp

MCP (Model Context Protocol) server for the **official Facebook Graph
API**. Exposes a complete toolset for Pages, Posts, Comments,
Likes/Reactions, Photos/Videos, Events and Insights, plus dedicated
tools to store and validate your Facebook credentials.

## Install & run

No install needed if you have [uv](https://docs.astral.sh/uv/):

```bash
uvx facebook-automata-mcp
```

Or install with pip:

```bash
pip install facebook-automata-mcp
facebook-automata-mcp
```

### Use with an MCP client (e.g. Claude Desktop / Claude Code)

```json
{
  "mcpServers": {
    "facebook": {
      "command": "uvx",
      "args": ["facebook-automata-mcp"]
    }
  }
}
```

## Credentials

You do **not** need to edit any config file by hand. Once the server is
connected to your MCP client, just ask it (in your own words) to
configure Facebook, which will call the `set_facebook_credentials`
tool, e.g.:

> "Set my Facebook access token to EAAB..."

This will:

1. Validate the token against `GET /me`.
2. Save it to `~/.facebook-automata-mcp/credentials.json` (created with
   `0700`/`0600` permissions, owner-only).
3. Return your validated identity (id/name).

Fields you can provide:

| field         | required | purpose                                                        |
|---------------|----------|------------------------------------------------------------------|
| `access_token`| yes      | User, Page, or App access token                                 |
| `app_id`      | no       | Enables `/debug_token` introspection (scopes, expiry)            |
| `app_secret`  | no       | Used together with `app_id` for `/debug_token`                   |
| `page_id`     | no       | Default Page ID used when a tool's `page_id` argument is omitted |
| `api_version` | no       | Graph API version, defaults to `v21.0`                           |

Check current credentials at any time with `check_facebook_credentials`
(does a live validation call) or `get_credentials_status` (offline,
just checks the file exists). Remove them with
`clear_facebook_credentials`.

Credentials can also be provided via environment variables instead of
(or in addition to) the stored file — env vars always win:

```
FACEBOOK_AUTOMATA_MCP_ACCESS_TOKEN=...
FACEBOOK_AUTOMATA_MCP_APP_ID=...
FACEBOOK_AUTOMATA_MCP_APP_SECRET=...
FACEBOOK_AUTOMATA_MCP_PAGE_ID=...
FACEBOOK_AUTOMATA_MCP_API_VERSION=v21.0
FACEBOOK_AUTOMATA_MCP_HOME=/custom/path   # overrides ~/.facebook-automata-mcp
```

### Getting a token

The quickest way for a Page is Meta's [Graph API
Explorer](https://developers.facebook.com/tools/explorer/): select your
app, generate a User Access Token with `pages_show_list`,
`pages_read_engagement`, `pages_read_user_content`,
`pages_manage_posts`, and `pages_manage_engagement`, then call
`get_my_accounts` here to fetch your Page's own (page-scoped) access
token, and use that as `access_token` for Page-level tools.

## Tools

**Credentials**
- `set_facebook_credentials` — save + validate a token
- `check_facebook_credentials` — live validation + `/debug_token` info
- `get_credentials_status` — offline check
- `clear_facebook_credentials` — delete stored credentials

**Identity**
- `get_my_profile`, `get_user_profile`, `get_my_accounts`

**Pages**
- `search_pages`, `get_page_info`, `get_page_posts`, `get_page_feed`,
  `get_page_tagged_posts`, `get_page_events`, `get_page_photos`,
  `get_page_videos`, `get_page_albums`, `get_page_insights`

**Posts**
- `get_post`, `publish_page_post`, `delete_post`

**Comments**
- `get_post_comments` (includes who commented), `get_comment`,
  `get_comment_replies`, `publish_comment`, `reply_to_comment`,
  `delete_comment`, `hide_comment`

**Likes / Reactions**
- `get_post_likes`, `get_post_reactions` (who + which reaction),
  `get_comment_likes`, `get_comment_reactions`, `like_object`,
  `unlike_object`

**Media**
- `upload_page_photo`, `upload_page_video`

**Escape hatch**
- `graph_api_get`, `graph_api_post`, `graph_api_delete` — call any
  Graph API edge not covered above

All list-style tools accept `limit` and `after` (pagination cursor from
the previous call's `next_cursor`) and return `{ok, data, paging,
next_cursor}`.

## Notes on Facebook API limitations

- Modern Graph API versions restrict most personal-profile fields and
  the classic "who liked this / friend list" data for regular users
  due to privacy policy — Page-owned content (Page posts, their
  comments, and reactions) is the primary supported use case.
- Some actions (posting, deleting, hiding comments, insights) require
  a **Page access token** with the relevant permissions
  (`pages_manage_posts`, `pages_manage_engagement`, `read_insights`,
  etc.) and, for public apps, Meta App Review.

## Development

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e .
facebook-automata-mcp
```

## Publish to PyPI

```bash
pip install build twine
python -m build
twine upload dist/*
```

Once published, anyone can run it with `uvx facebook-automata-mcp`
without installing anything permanently.

## License

MIT