facebook-mcp-server

Facebook Pages MCP Server

A Model Context Protocol (MCP) server for the Facebook Graph API (Pages). Enables Claude Desktop and other MCP clients to read insights, create posts, manage comments, and more — all through the Facebook Pages API.

Features

SENSE Tools (Read)

Tool	Description
fb_get_page_insights	Page-level metrics: impressions, reach, engagements, follower count
fb_get_post_insights	Post-level metrics: impressions, clicks, reactions
fb_get_comments	Comments on a post with author info, likes, replies
fb_get_page_feed	Your published posts with permalinks, shares, timestamps

ACT Tools (Write)

Tool	Description
fb_create_post	Create text, link, photo, or video posts. Supports first-comment for CTAs
fb_reply_comment	Reply to a comment on a post
fb_delete_post	Delete a post you published

Quick Start

Prerequisites

• Node.js 18+
• A Facebook Page Access Token (how to get one)
• Your Facebook Page ID

Install

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

Configure

cp .env.example .env
# Edit .env with your credentials:
#   FACEBOOK_ACCESS_TOKEN=your_long_lived_facebook_page_token_here
#   FACEBOOK_PAGE_ID=your_facebook_page_id_here

Run

# Development
npm run dev

# Production
npm start

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "facebook": {
      "command": "node",
      "args": ["/path/to/facebook-mcp-server/dist/index.js"],
      "env": {
        "FACEBOOK_ACCESS_TOKEN": "your_token_here",
        "FACEBOOK_PAGE_ID": "your_page_id_here"
      }
    }
  }
}

Architecture

• Transport: stdio (standard MCP protocol)
• API: Facebook Graph API v21.0
• Rate Limiting: Built-in token-bucket rate limiter (200 calls/hour global, 25 publishes/day) with per-tenant isolation
• Retry: Automatic exponential backoff on 429s (up to 3 retries)
• Security: Input sanitization against prompt injection (zero-width chars, whitespace abuse, context flooding)
• Error Handling: Structured errors with actionable action hints for agents

Development

# Run tests
npm test

# Development server (auto-reload)
npm run dev

# Type check
npx tsc --noEmit

# Build
npm run build

Testing

The test suite covers:

• client.test.ts — Graph API HTTP client, URL construction, error parsing
• create-post.test.ts — Post creation validation and endpoint routing
• errors.test.ts — Error mapping and agent-action hint strings
• first-comment.test.ts — First-comment partial-success contract
• handlers.test.ts — Full tool handler integration tests
• rate-limiter.test.ts — Token bucket, per-tenant isolation, retry logic
• response.test.ts — MCP response formatting
• sanitize.test.ts — Prompt injection protection
• tools.test.ts — safeHandler and credential resolution

npm test

License

MIT