# @m8lab/mcp-facebook

[![npm version](https://img.shields.io/npm/v/@m8lab/mcp-facebook.svg)](https://www.npmjs.com/package/@m8lab/mcp-facebook)
[![CI](https://github.com/lmtNoLimit/mcp-facebook/actions/workflows/ci.yml/badge.svg)](https://github.com/lmtNoLimit/mcp-facebook/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

MCP server for Facebook Pages — create posts, manage comments, and get insights via Claude Code/Desktop. Uses the Facebook Graph API v25.0 directly with no Facebook SDK dependency.

## Requirements

- Node.js >= 18.0.0
- Facebook Page Access Token with the required permissions (see [Setup](#environment-variables))

## Install

### Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "facebook": {
      "command": "npx",
      "args": ["-y", "@m8lab/mcp-facebook"],
      "env": {
        "FACEBOOK_PAGE_ID": "your_page_id",
        "FACEBOOK_PAGE_ACCESS_TOKEN": "your_page_access_token"
      }
    }
  }
}
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "facebook": {
      "command": "npx",
      "args": ["-y", "@m8lab/mcp-facebook"],
      "env": {
        "FACEBOOK_PAGE_ID": "your_page_id",
        "FACEBOOK_PAGE_ACCESS_TOKEN": "your_page_access_token"
      }
    }
  }
}
```

## Available Tools

| Tool | Description |
|---|---|
| `facebook_create_post` | Publish an immediate post (text, link, picture) |
| `facebook_schedule_post` | Schedule a post 10 min–6 months in the future |
| `facebook_delete_post` | Permanently delete a post by ID |
| `facebook_get_posts` | List recent Page feed posts (up to 100) |
| `facebook_get_comments` | List comments on a specific post (up to 100) |
| `facebook_reply_comment` | Reply to an existing comment |
| `facebook_hide_comment` | Hide or unhide a comment |
| `facebook_get_insights` | Retrieve Page-level analytics (views, fans, engagement) |

## Environment Variables

| Variable | Description |
|---|---|
| `FACEBOOK_PAGE_ID` | Numeric ID of your Facebook Page (e.g. `123456789012345`) |
| `FACEBOOK_PAGE_ACCESS_TOKEN` | Long-lived Page Access Token with the required permissions |

### How to Get Your Page Access Token

1. Go to [Meta for Developers](https://developers.facebook.com/) and create or open an App.
2. Under **Use Cases**, add **Pages** and request the following permissions:
   - `pages_manage_posts` — create, schedule, delete posts
   - `pages_read_engagement` — read posts and comments
   - `pages_manage_engagement` — reply to and hide comments
   - `pages_read_user_content` — read comments
   - `read_insights` — access Page analytics
3. In the [Graph API Explorer](https://developers.facebook.com/tools/explorer/):
   - Select your App and your Page under **User or Page**.
   - Click **Generate Access Token** and approve all required permissions.
   - Use the token expander in [Access Token Debugger](https://developers.facebook.com/tools/debug/accesstoken/) to convert it to a long-lived token (~60 days) or generate a never-expiring System User token via Business Manager.
4. Your Page ID is the number in your Page's About section or visible in the Graph API Explorer dropdown.

> **App Review Note:** For a live app serving users other than yourself and your test users, Facebook requires [App Review](https://developers.facebook.com/docs/app-review) for `pages_manage_posts` and related permissions. During development you can use the token for your own pages without review.

## Development

```bash
# Clone the repo
git clone https://github.com/lmtNoLimit/mcp-facebook.git
cd mcp-facebook

# Install dependencies
npm install

# Type check
npm run typecheck

# Build
npm run build

# Watch mode
npm run dev
```

Copy `.env.example` to `.env` and fill in your credentials to run locally:

```bash
cp .env.example .env
# Edit .env with your FACEBOOK_PAGE_ID and FACEBOOK_PAGE_ACCESS_TOKEN
node dist/index.js
```

## License

MIT — see [LICENSE](LICENSE)