Facebook MCP Server

A stateless Model Context Protocol (MCP) server for Facebook Graph API integration with user profile, social data, and content access capabilities.

Features

• 7 User Data Tools: Access to Facebook user profile and social data
• Page-Based Pagination: Navigate through data using page numbers (page 1, 2, 3...)
• Enhanced Descriptions: LLM-friendly parameter descriptions for better tool usage
• Stateless Architecture: Each request is independent with no session management
• Bearer Token Auth: Per-request authentication via Authorization header
• Facebook Graph API v22.0: Latest stable API version

Quick Start

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm
• Facebook Access Token with appropriate scopes

Installation

# Install dependencies
pnpm install

# Build TypeScript
pnpm run build

# Start production server
pnpm start

# Start development server with hot reload
pnpm run dev

Docker

# Build image
docker build -t facebook-mcp-server .

# Run container
docker run -p 30003:30003 facebook-mcp-server

Endpoints

• POST /mcp - Main MCP endpoint for tool execution
• GET /health - Health check endpoint

Default port: 30003

Authentication

All requests require a Facebook Access Token via Authorization header:

Authorization: Bearer <facebook-access-token>

Create a Facebook App and get a User Access Token with these scopes:

• public_profile - Basic profile info (always granted)
• email - User's email address
• user_friends - Friends who also use the app
• user_photos - User's uploaded photos
• user_posts - User's timeline posts
• user_videos - User's uploaded videos
• user_likes - Pages/things the user has liked

Note: Only public_profile and email are available without Facebook App Review. Other scopes require approval.

Tools (7 total)

User Tools (7)

| Tool | Description | Required Scope | |------|-------------|----------------| | get_me | Get current user's profile information | public_profile | | get_friends | Get user's friends who also use the app | user_friends | | get_photos | Get user's uploaded photos | user_photos | | get_user_posts | Get user's timeline posts | user_posts | | get_videos | Get user's uploaded videos | user_videos | | get_likes | Get pages/things the user has liked | user_likes | | get_permissions | Get permissions granted to the access token | public_profile |

Usage Examples

Get user profile

curl -X POST http://localhost:30003/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <facebook-access-token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "get_me",
      "arguments": {}
    }
  }'

Get user's posts

curl -X POST http://localhost:30003/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <facebook-access-token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/call",
    "params": {
      "name": "get_user_posts",
      "arguments": {
        "limit": 10
      }
    }
  }'

Pagination example

The following tools support pagination: get_friends, get_photos, get_user_posts, get_videos, get_likes

# Page 1 (first 25 posts)
curl -X POST http://localhost:30003/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <facebook-access-token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "get_user_posts",
      "arguments": {
        "page": 1,
        "limit": 25
      }
    }
  }'

# Response includes pagination info:
# {
#   "success": true,
#   "posts": [...],
#   "pagination": {
#     "page": 1,
#     "limit": 25,
#     "total": 150,
#     "pages": 6,
#     "hasNext": true,
#     "hasPrev": false
#   }
# }

# Page 2 (posts 26-50)
curl -X POST http://localhost:30003/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <facebook-access-token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/call",
    "params": {
      "name": "get_user_posts",
      "arguments": {
        "page": 2,
        "limit": 25
      }
    }
  }'

# Jump to page 5 (posts 101-125)
curl -X POST http://localhost:30003/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <facebook-access-token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "tools/call",
    "params": {
      "name": "get_user_posts",
      "arguments": {
        "page": 5,
        "limit": 25
      }
    }
  }'

Check token permissions

curl -X POST http://localhost:30003/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <facebook-access-token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "tools/call",
    "params": {
      "name": "get_permissions",
      "arguments": {}
    }
  }'

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | PORT | Server port | 30003 | | DEBUG | Enable debug output | false |

Development

# Run with hot reload
pnpm run dev

# Run with debug logging
DEBUG=true pnpm run dev

# Type check
pnpm run build

# Run tests
pnpm test

License

PROPRIETARY - BlueNexus AI