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:

uvx facebook-automata-mcp

Or install with pip:

pip install facebook-automata-mcp
facebook-automata-mcp

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

{
  "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: 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

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

Publish to PyPI

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