facebook-pages-mcp

MCP server for Facebook Pages organic analytics and management, powered by Meta Graph API v25.0.

Built for Claude Code and any MCP-compatible AI tool. Gives your AI assistant direct access to your Facebook Page data — posts, insights, comments, and more.

Part of The SEO Engine toolkit by Rex Jones — AI-powered SEO and social media tooling for agencies and businesses.

Why this exists

• No good Facebook Pages MCP server existed. Instagram has several. Facebook Pages had none that worked on a current API version.
• Meta deprecated legacy metrics on June 15, 2026. page_impressions, page_reach, and page_impressions_unique no longer return data. This server uses the replacement metrics from day one.
• Business Manager support. Most businesses manage Pages through Meta Business Manager, not personal accounts. This server works with both.

Quick start

Option 1: npx (no install)

{
  "mcpServers": {
    "facebook-pages": {
      "command": "npx",
      "args": ["-y", "facebook-pages-mcp"],
      "env": {
        "FB_PAGE_ACCESS_TOKEN": "your_page_access_token",
        "FB_PAGE_ID": "your_page_id"
      }
    }
  }
}

Option 2: Clone and build

git clone https://github.com/lanternrow/facebook-pages-mcp.git
cd facebook-pages-mcp
npm install
npm run build

Then add to your Claude Code MCP settings:

{
  "mcpServers": {
    "facebook-pages": {
      "command": "node",
      "args": ["/path/to/facebook-pages-mcp/dist/index.js"],
      "env": {
        "FB_PAGE_ACCESS_TOKEN": "your_page_access_token",
        "FB_PAGE_ID": "your_page_id"
      }
    }
  }
}

Getting your Page Access Token

Step 1: Create a Meta App

1. Go to Meta for Developers and click Create App
2. Name your app and choose the "Manage everything on your Page" use case
3. Connect it to your Business Portfolio

Step 2: Generate a token in the Graph API Explorer

1. Open the Graph API Explorer
2. Select your app from the Meta App dropdown
3. Add permissions: pages_show_list, pages_read_engagement, business_management
4. Click Generate Access Token and complete the OAuth flow
5. When asked about Pages, select "Opt in to all current and future Pages"

Step 3: Get your Page Access Token

If your Pages are managed through Business Manager (most businesses):

# First, find your business ID
GET /me/businesses?fields=id,name

# Then get Page tokens for that business
GET /{business-id}/owned_pages?fields=id,name,access_token

If your Pages are on your personal account:

GET /me/accounts?fields=id,name,access_token

Copy the access_token and id for the Page you want.

Step 4: Exchange for a long-lived token (recommended)

Short-lived tokens expire in ~1 hour. Exchange for a long-lived token (~60 days):

GET /oauth/access_token
  ?grant_type=fb_exchange_token
  &client_id={your-app-id}
  &client_secret={your-app-secret}
  &fb_exchange_token={short-lived-token}

Tip: For Pages you admin, Page tokens derived from a long-lived User Token never expire.

Tools

Read tools

| Tool | Description | |------|-------------| | get_page_info | Page metadata: name, category, follower count, contact info, cover photo | | get_page_insights | Page-level analytics with date ranges and period aggregation (day/week/28-day) | | get_published_posts | Paginated list of posts authored by the Page | | get_post_insights | Per-post engagement: impressions, clicks, reactions by type | | get_post_comments | Paginated comments with author info and like/reply counts | | get_video_insights | Video performance: views, watch time, reactions | | get_page_feed | Full feed including visitor posts |

Write tools

| Tool | Description | |------|-------------| | create_post | Publish text, link, or photo posts to the Page |

Utility tools

| Tool | Description | |------|-------------| | refresh_token_info | Check token validity, expiration, and granted scopes |

Metrics and the June 2026 deprecation

Meta deprecated these page-level metrics on June 15, 2026:

| Deprecated | Replacement | |-----------|-------------| | page_impressions | page_views_total | | page_reach | Page Viewer metric (rolling out) | | page_impressions_unique | Media Viewers metric (rolling out) |

This server uses only non-deprecated metrics: page_views_total, page_fans, page_fan_adds, page_fan_removes, page_actions_post_reactions_total.

Architecture

src/
  index.ts          # MCP server entry point, tool registration
  client.ts         # Graph API HTTP client (native fetch, no dependencies)
  types.ts          # TypeScript interfaces for API responses
  tools/
    pages.ts        # get_page_info, get_page_feed
    insights.ts     # get_page_insights, get_video_insights
    posts.ts        # get_published_posts, get_post_insights, get_post_comments, create_post
    utils.ts        # refresh_token_info

• Zero external HTTP dependencies — uses Node 18+ native fetch
• Rate limit tracking — captures x-app-usage and x-page-usage headers
• Cursor-based pagination — all list endpoints support after cursor and configurable limits
• Zod validation — all tool inputs validated with descriptive error messages

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | FB_PAGE_ACCESS_TOKEN | Yes | Long-lived Page Access Token | | FB_PAGE_ID | Yes | Default Facebook Page ID (numeric) |

Development

npm run dev    # Watch mode — recompiles on save
npm run build  # Production build
npm start      # Run the server

Contributing

Issues and PRs welcome. If Meta changes the API (they will), please open an issue.

License

MIT — see LICENSE.

Built as part of The SEO Engine by Rex Jones.