Facebook Pages MCP Server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| FB_TIMEOUT | No | HTTP timeout in seconds (default 30). | 30 |
| MCP_API_KEY | No | Bearer token(s) clients must present to use this MCP server when using serve-http. Comma-separated list supported. | |
| FB_PAGE_TOKEN | Yes | Facebook Page access token. Required. Every Page tool acts with it. Never a tool parameter. | |
| FB_USER_TOKEN | No | Optional user access token for me/accounts (pages_list, pages_find). Unset means those calls use FB_PAGE_TOKEN. | |
| FB_VERIFY_SSL | No | true (default) or false. Set false only for a local test double with a self-signed certificate. | true |
| MCP_HTTP_HOST | No | Bind host for serve-http (default 127.0.0.1). | 127.0.0.1 |
| MCP_HTTP_PORT | No | Bind port for serve-http (default 8900). | 8900 |
| MCP_LOG_LEVEL | No | DEBUG, INFO, WARNING, or ERROR (default INFO). Logs go to stderr. | INFO |
| FB_MAX_RETRIES | No | Extra retries on transient Graph failures (default 2). | 2 |
| FB_GRAPH_VERSION | No | Graph API version (default v25.0). Accepts v25.0 or 25.0. | v25.0 |
| FB_GRAPH_BASE_URL | No | Graph API base URL (default https://graph.facebook.com). Change only for a test double or proxy. | https://graph.facebook.com |
| MCP_ALLOWED_HOSTS | No | Comma-separated Host allowlist for the HTTP transport. | |
| MCP_ALLOWED_ORIGINS | No | Comma-separated browser Origin allowlist for the HTTP transport. | |
| MCP_TOOL_PERMISSIONS | No | read, write, delete, comma-separated. Default (unset): read. | read |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Start with pages_list or pages_find to get a page_id, then read Page data with page_get, page_posts_list, post_comments_list, page_insights and the other read tools. The Graph API returns only the fields you ask for; read tools ship sensible defaults and accept fields or extra_fields to change them. Edges are paginated: when more_available is true, pass next_url to graph_follow. Insights need metric names; page_insights_metrics lists names worth trying. A Facebook access token normally comes from the server environment. Any tool also accepts an access_token argument, which is used for that call alone: pass the token you hold when the configured one is expired or is not yours. Tool permissions for this server (enabled: read tools (fetch data only)).
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| pages_listB | List the Pages the token's person manages List the Facebook Pages the access token's person can perform tasks on, with the tasks (ADVERTISE, MODERATE, CREATE_CONTENT, ANALYZE, ...) they hold on each. Use this first to find a page_id. Graph API: GET me/accounts. Needs a User access token with pages_show_list. Set FB_USER_TOKEN for a dedicated user token, or use a Page token issued through a person. |
| pages_findA | Find a Page by name among the managed Pages Search the Pages the token manages by a case-insensitive substring of the Page name or username. Returns matching page ids and names. Cheaper than listing every Page when you only need one. Graph API: GET me/accounts (filtered locally). |
| page_getA | Read a Page's fields Read one Page's details: name, category, about, follower and like counts, contact info, opening hours, location, picture, verification status. Pass fields to choose exactly what you need, or extra_fields to add to the defaults. Graph API: GET {page_id}. |
| page_posts_listA | List a Page's posts List posts published by a Page, newest first, with message, timestamp, engagement counts and attachment metadata. Filter by date with since/until (Unix timestamps), paginate with limit and after. Graph API: GET {page_id}/posts. |
| post_getB | Read one post Read a single post by id (PageID_RecipientID). Returns the message, timestamps, link, picture, share and reaction summaries. Graph API: GET {post_id}. |
| post_comments_listB | List comments on a post List comments on a post. Defaults to top-level comments; set filter=stream for the full threaded stream, order=chronological_ascending to read oldest first. Graph API: GET {post_id}/comments. |
| page_insightsA | Read Page metrics Read Page-level metrics (reach, engagements, follower growth, video views, reactions, demographics). Pass one or more metric names, a period (day, week, days_28, lifetime) and either date_preset or since/until. Call page_insights_metrics for a list of metric names to try. Graph API: GET {page_id}/insights. Requires a token that can perform the ANALYZE task, and Pages with fewer than 100 likes return no insights. Some metrics are deprecated in newer API versions; an invalid-metric error names the metric that failed. |
| post_insightsB | Read one post's metrics Read metrics for a single post: reach, clicks, media views, reactions by type, video views. Pass one or more metric names. Graph API: GET {post_id}/insights. |
| page_insights_metricsB | List Page Insights metric names to try List common Page and post Insights metric names grouped by purpose, plus the periods and date presets the API accepts. Retired metrics are listed separately with their replacements, because one retired metric fails the whole Insights request. Meta changes this list often, so treat it as a starting point and let the API tell you when a metric is unavailable. Graph API: (static reference). |
| page_photos_listC | List a Page's photos List photos posted to a Page, with image URLs, captions and comment counts. Graph API: GET {page_id}/photos. |
| page_videos_listC | List a Page's videos List videos published by a Page, with length, permalinks, thumbnail and publish status. Graph API: GET {page_id}/videos. |
| page_albums_listC | List a Page's photo albums List a Page's photo albums with names, counts and links. Graph API: GET {page_id}/albums. |
| page_events_listC | List a Page's events List events created by a Page with start and end times, place and attendee counts. Graph API: GET {page_id}/events. |
| page_conversations_listB | List a Page's message conversations List Messenger conversations a Page has with people, with the last snippet, participants and unread count. Needs a token with pages_messaging. Graph API: GET {page_id}/conversations. |
| conversation_messages_listB | List messages in a conversation Read the messages of one Page conversation, newest first. Graph API: GET {conversation_id}/messages. |
| token_debugA | Inspect an access token's app, scopes and expiry Debug a Facebook access token: which app issued it, the granted scopes, the Page or user it belongs to, and when it expires. Omit input_token to inspect the token this server is configured with. Graph API: GET debug_token. Needs an app access token to see other apps' tokens; a Page token can debug itself. |
| graph_followA | Follow a Graph API pagination link Fetch the next page of an edge from the next_url a previous read returned. Graph pagination links already carry the cursor and token, so this is the reliable way to page through a long edge. Graph API: GET . |
| graph_batchB | Run several Graph API calls in one request Run a batch of Graph API requests in one call to save round trips. Each entry is {method, relative_url, name}, where relative_url is a Graph path such as '1001/posts'. GET entries are always allowed; POST and DELETE entries need the write permission. Graph API: POST batch. A batch entry without relative_url has no target, and Graph answers it as a request on the version root: 'Unsupported get request'. |
| facebook_pages_statusA | Report this server's configuration, readiness, and token expiry Report the configured Graph API version, the enabled tool permissions, and the Facebook token's type, scopes and expiry. The token is checked live with debug_token, so an expired token is reported as expired rather than shown as configured. Set ping=false to skip the live call. Graph API: (local) plus GET /debug_token. |
| facebook_pages_set_tokenA | Use a different Facebook access token for the rest of this session Verify a pasted access token with debug_token, then use it for every later call in this process. Use it when the configured token has expired and a new one has just been minted: no restart is needed. scope 'page' replaces FB_PAGE_TOKEN, scope 'user' replaces FB_USER_TOKEN. The token is not written to the environment, so a restart goes back to the configured value. A token that debug_token rejects is not applied. Graph API: (local) after GET /debug_token. |
| facebook_pages_refresh_tokenA | Mint a Page access token that does not expire, and use it now Exchange a User access token for a long-lived one with the app's credentials, read me/accounts with it, and use the Page token that returns for every later call in this process. A Page token taken from a long-lived User token has no expiry, so this is how to stop the token expiring. Needs FB_APP_ID and FB_APP_SECRET, and a User token that has not expired: pass user_token, or have FB_USER_TOKEN set. The token is not written to the environment, so set FB_PAGE_TOKEN to keep it after a restart. Graph API: GET /oauth/access_token then GET me/accounts. A User token cannot be exchanged after it has expired; a new one must be obtained from the Graph API Explorer. The App Secret is sent only to the token exchange, never with a Page call. |
| facebook_pages_list_toolsA | List the tools this server exposes List every tool the AI may call, grouped by tier, with the Graph API endpoint behind each. Use this to discover what is available. Graph API: (local). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 22 tools
Most tools map to a single resource+action (page_get, post_get, page_photos_list), so an agent can pick correctly. A few pairs overlap: pages_list vs pages_find, page_insights vs page_insights_metrics, and token_debug vs facebook_pages_status all answer similar questions, and set_token vs refresh_token both change the session token, but descriptions distinguish them.
All names are snake_case and follow a resource-first pattern (page_*, post_*, graph_*), which is readable and predictable. Minor deviations: the collection prefix is plural 'pages_' for two tools, admin/utility tools use a different 'facebook_pages_' prefix, and page_insights_metrics lacks an action verb.
22 tools is on the heavy side but each maps to a distinct Graph API edge or utility (posts, comments, insights, photos, videos, albums, events, messaging, auth, pagination, batch). Some listing tools could be collapsed into a generic edge reader, but nothing is clearly redundant.
The surface is almost entirely read-only: there are no direct tools to publish a post, reply to or moderate a comment, send a Messenger message, upload media, or create an event, which are core Facebook Pages workflows. graph_batch is an escape hatch for writes, but only if the agent already knows the raw Graph paths and has the write permission.