facebook-mcp

# facebook-mcp — Facebook Pages MCP Server

| [![CI](https://img.shields.io/github/actions/workflow/status/IvanBBaev/facebook-mcp/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=CI)](https://github.com/IvanBBaev/facebook-mcp/actions/workflows/ci.yml) | [![CodeQL](https://img.shields.io/github/actions/workflow/status/IvanBBaev/facebook-mcp/codeql.yml?branch=main&style=flat-square&logo=github&label=CodeQL)](https://github.com/IvanBBaev/facebook-mcp/actions/workflows/codeql.yml) |             [![License: MIT](https://img.shields.io/github/license/IvanBBaev/facebook-mcp?style=flat-square&color=blue&label=license)](LICENSE)             |              [![node](https://img.shields.io/badge/node-%E2%89%A522-brightgreen?style=flat-square&logo=nodedotjs&logoColor=white)](package.json)              | [![MCP](https://img.shields.io/badge/MCP-server-orange?style=flat-square)](https://modelcontextprotocol.io) |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------: |
|                                                                           [![status](https://img.shields.io/badge/status-pre--1.0-yellow?style=flat-square)](#)                                                                            |              [![last commit](https://img.shields.io/github/last-commit/IvanBBaev/facebook-mcp?style=flat-square&logo=git&logoColor=white&label=last%20commit)](https://github.com/IvanBBaev/facebook-mcp/commits/main)              | [![docs](https://img.shields.io/badge/docs-github.io-1877F2?style=flat-square&logo=readthedocs&logoColor=white)](https://ivanbbaev.github.io/facebook-mcp/) | [![Sponsor](https://img.shields.io/badge/Sponsor-GitHub-ea4aaa?style=flat-square&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/IvanBBaev) |                                                                                                             |

📖 **[Documentation site →](https://ivanbbaev.github.io/facebook-mcp/)**

A local-first TypeScript [Model Context Protocol](https://modelcontextprotocol.io)
(MCP) server for the **Meta Graph API**, focused on **Facebook Pages** —
publishing, reading & insights, and comment/message moderation — driven from an
MCP client (Claude, VS Code, the Inspector…) and operated locally by a Page admin
using their own Meta developer app. Least-privilege tokens, plan-and-apply write
safety, and no telemetry.

> 🚧 **Status: pre-1.0, in active development. Not yet published to npm.**
>
> All seven tool packages are implemented — see the [tool table](#tools) for the
> exact surface. **Nothing has been verified against the live Graph API yet.**
> Every test in this repository runs against fakes and recorded fixtures behind a
> network fence that throws on a real `fetch`, so "the tests pass" means "the code
> does what the fixtures say", not "Meta accepted it". A live smoke harness
> exists ([`scripts/smoke/`](scripts/smoke/README.md)) but has not been run
> against a real Page as part of any released state. Treat every capability below
> as **implemented but unproven**, expect breaking changes until the first tagged
> release, and read [Known limitations](#known-limitations) before you rely on
> anything.

**Contents:** [Features](#features) · [Requirements](#requirements) ·
[Setup](#setup) · [Client compatibility](#client-compatibility) ·
[Configure credentials](#configure-credentials) ·
[Permissions](#permissions-you-need-to-grant) · [Tools](#tools) ·
[How this compares](#how-this-compares) ·
[Known limitations](#known-limitations) · [Not in scope](#not-in-scope) ·
[Your responsibilities](#your-responsibilities-as-the-operator) ·
[Roadmap](#roadmap) · [Security notes](#security-notes) ·
[Documentation](#documentation) · [Support](#support) ·
[Trademark](#trademark) · [License](#license)

## Features

Implementation status only — see the status note above for what "implemented"
does and does not mean.

| Area                   | Capability                                                                      | Status                            |
| ---------------------- | ------------------------------------------------------------------------------- | --------------------------------- |
| **Core & diagnostics** | Identity, Page listing, rate-limit usage, `doctor` pre-flight check             | ✅ Implemented, not live-verified |
| **Reading**            | Page & post reads, Reels, reactions, cursor pagination                          | ✅ Implemented, not live-verified |
| **Publishing**         | Text / link / photo / video / Reels posts, scheduling, edit & delete            | ✅ Implemented, not live-verified |
| **Insights**           | Page & post insights, flat rows + per-metric summaries, deprecation-aware       | ✅ Implemented, not live-verified |
| **Moderation**         | Comment reads, replies, hide/delete, private reply, block/unblock               | ✅ Implemented, not live-verified |
| **Messaging**          | Conversation reads and replies within the 24-hour window                        | ✅ Implemented, not live-verified |
| **Ads**                | Campaign/adset/ad reads, insights, status & budget control — **off by default** | ✅ Implemented, not live-verified |
| **Live verification**  | Every tool exercised against a real Page and a real ad account                  | ❌ Not done — see the status note |
| **npm / MCPB release** | `npx @ivanbaev/facebook-mcp`, signed bundle, registry listing                   | ❌ Not published                  |

The default profile exposes a deliberately small, curated tool surface — each
tool wraps one real capability rather than mirroring every Graph edge.

- **Local-first, no telemetry.** Only three Meta hosts are ever reached
  (`graph`, `graph-video`, `rupload`); nothing phones home.
- **Least-privilege credentials.** Works with a never-expiring System User token
  (Business Manager) or a long-lived Page token — no App Review required for an
  admin operating their own assets.
- **Safe writes.** Tiered plan-and-apply gating; irreversible and spend actions
  require out-of-band confirmation and are never bypassed by an env flag.
- **Secret hygiene.** Value-based redaction at a single choke-point across logs,
  errors, tool results, and the write journal.
- **Layered architecture.** Lint-enforced `core ← api ← mcp ← tools` layering,
  tools-as-data with a central package registry.

## Requirements

- Node.js **≥ 22** (enforced by `engines` and a runtime guard in the launcher;
  the project targets the version in `.nvmrc`).
- A Meta (Facebook) developer app — a **Business**-type app at Standard Access is
  enough; no App Review is needed to operate your own assets.
- A Facebook **Page** (and, for the opt-in `ads` package, an **ad account**) you
  administer.

## Setup

### (a) From source (the only way today)

The package is not on npm yet, so build from a clone:

```bash
git clone https://github.com/IvanBBaev/facebook-mcp.git
cd facebook-mcp
npm install
npm run build
node build/index.js doctor   # pre-flight: token, scopes, package matrix
node build/index.js          # or: ./bin/facebook-mcp.mjs
```

Configure credentials (see [below](#configure-credentials)), then point your MCP
client at that command with an absolute path:

```json
{
  "mcpServers": {
    "facebook": {
      "command": "node",
      "args": ["/absolute/path/to/facebook-mcp/build/index.js"],
      "env": { "FB_SYSTEM_TOKEN": "…", "FB_PAGE_ID": "…" }
    }
  }
}
```

### (b) Via npx (after the first release)

> Both snippets below become available **after the first published release** —
> the package is currently unpublished, so they do not work yet.

```json
{
  "mcpServers": {
    "facebook": {
      "command": "npx",
      "args": ["-y", "@ivanbaev/facebook-mcp"]
    }
  }
}
```

**Claude Code plugin** (installs the server wired up):

```bash
/plugin marketplace add IvanBBaev/facebook-mcp
/plugin install facebook-mcp
```

## Client compatibility

This is a standard stdio MCP server with no client-specific code, so it should
work anywhere the protocol does. **"Should" is the operative word:** the table
records the configuration each client needs and whether that path has actually
been exercised — not a promise.

| Client                             | How you register it                                              | Verified?                                      |
| ---------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- |
| **Claude Desktop**                 | `claude_desktop_config.json` → `mcpServers`, or a `.mcpb` bundle | ❌ Not yet — bundle never installed end-to-end |
| **Claude Code**                    | `claude mcp add`, or the plugin marketplace in this repo         | ❌ Not yet                                     |
| **VS Code (Copilot Chat / agent)** | `.vscode/mcp.json` → `servers`                                   | ❌ Not yet                                     |
| **Cursor**                         | `~/.cursor/mcp.json` → `mcpServers`                              | ❌ Not yet                                     |
| **W