# 🚀 PagePilot MCP

**🌐 Language / Ngôn ngữ:** **English** · [Tiếng Việt](./README.vi.md)

> **An MCP server that lets AI agents manage a Facebook Fanpage through the official Graph API — safe, no scraping, and never touching private messages.**

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-orange)](https://modelcontextprotocol.io/)
[![Facebook Graph API](https://img.shields.io/badge/Facebook-Graph%20API%20v22.0-1877F2?logo=facebook&logoColor=white)](https://developers.facebook.com/docs/graph-api/)

---

## 📑 Table of Contents

- [Introduction](#-introduction)
- [Key Features](#-key-features)
- [Why Is It Safe?](#-why-is-it-safe)
- [Requirements](#-requirements)
- [Getting a Facebook Token](#-getting-a-facebook-token)
- [Installation & Running](#-installation--running)
- [MCP Client Configuration](#-mcp-client-configuration)
- [The 29 Tools](#-the-29-tools)
- [Project Structure](#-project-structure)
- [Environment Variables](#-environment-variables)
- [Disclaimer](#-disclaimer)
- [License](#-license)
- [Author](#-author)

---

## 🌟 Introduction

**PagePilot MCP** is an **MCP (Model Context Protocol) server** written in Python that lets AI agents such as **Claude Desktop**, **Cursor**, or any **MCP client** directly **manage a Facebook Fanpage** through the official **Facebook Graph API**.

Instead of opening a browser and doing everything by hand, you simply give your AI agent instructions in natural language — and PagePilot takes care of the rest: publishing posts, scheduling, moderating comments, and analyzing performance.

> 💡 Every action goes through a **legitimate Page Access Token** that you yourself grant. No cookies, no scraping, no hacks.

---

## ✨ Key Features

- 📝 **Versatile posting** — text, photos, links; create / edit / delete posts and **schedule posts** for future publishing.
- 💬 **Smart comment moderation** — reply, hide / unhide, delete, **bulk operations**, and automatic **negative comment filtering**.
- 📊 **In-depth analytics** — fan count, post insights, reactions, and like / share / comment counts.
- 🔐 **Token management** — check Page status, debug tokens, and swap to a **long-lived token (~60 days)** with a single command.
- 🛡️ **Robust Graph client** — automatically handles network / Graph API errors, with a configurable timeout.
- 🧩 **29 MCP tools**, neatly organized into 4 clear groups.

---

## 🔒 Why Is It Safe?

PagePilot is built on a **"safety first"** principle:

1. **It uses only the official Facebook Graph API.** No cookies, no HTML scraping, no browser automation. That means it **does not violate Facebook's security mechanisms** and carries **no risk of getting banned** for abnormal behavior.

2. **It uses only a legitimate Page Access Token** — a token that you (the Page admin) grant through Facebook's standard OAuth flow.

3. **🚫 It DELIBERATELY excludes all messaging / Messenger / DM functionality.** PagePilot does **NOT** read, send, or touch anyone's private messages. This tool does exactly one thing: **manage a Page's public content** — publishing posts, moderating comments, and analytics. User privacy is fully respected.

> In short: PagePilot is a **Page administration assistant**, not a tool for spamming messages or tracking users.

---

## 📋 Requirements

- **Python 3.10+** (**Python 3.12** recommended)
- A **Facebook Fanpage** for which you are an admin
- A **Facebook App** of type *Business* (to obtain a token and grant permissions)
- Any MCP client (Claude Desktop, Cursor, etc.)

---

## 🔑 Getting a Facebook Token

Follow these steps to obtain a **Page Access Token** and **Page ID**:

1. Go to [developers.facebook.com](https://developers.facebook.com/) → **Create App** → choose the **Business** type.
2. Open the **Graph API Explorer** (Tools → Graph API Explorer).
3. In the dropdown, select your **Page** (instead of *User*).
4. Grant the following permissions (scopes):
   - `pages_manage_posts` — create / edit / delete posts
   - `pages_read_engagement` — read engagement (likes, comments, shares)
   - `pages_manage_engagement` — moderate comments (hide, delete, reply)
   - `pages_read_user_content` — read user-generated content on the Page
   - `read_insights` — read analytics (insights)
5. Click **Generate Access Token** → copy the **Page Access Token**.
6. Get your **Page ID**: go to the Page → *About* → *Page transparency*, or use the `page_status` tool itself once configured.

> ⏳ **Recommended:** The default token from the Explorer only lasts a few hours. Swap it for a **long-lived token (~60 days)** using the `exchange_long_lived_token` tool (requires `FB_APP_ID` and `FB_APP_SECRET`).

---

## ⚙️ Installation & Running

```bash
# 1. Clone the project
git clone https://github.com/Thangterter-Pipo/pagepilot-mcp.git
cd pagepilot-mcp

# 2. Create a virtual environment (pick one)
python -m venv .venv          # the standard way
# or
uv venv                       # if you use uv (faster)

# Activate the venv
source .venv/bin/activate      # Linux / macOS
.venv\Scripts\activate         # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Create a .env file from the template and fill in your token
cp .env.example .env
# Open .env and fill in FB_PAGE_ACCESS_TOKEN, FB_PAGE_ID...

# 5. Run the MCP server
python -m pagepilot.server
```

---

## 🧩 MCP Client Configuration

Example configuration for **Claude Desktop** (the `claude_desktop_config.json` file):

```json
{
  "mcpServers": {
    "pagepilot": {
      "command": "python",
      "args": ["-m", "pagepilot.server"],
      "cwd": "/path/to/pagepilot-mcp",
      "env": {
        "FB_PAGE_ACCESS_TOKEN": "EAAB...your-token",
        "FB_PAGE_ID": "1234567890",
        "FB_APP_ID": "optional",
        "FB_APP_SECRET": "optional",
        "FB_GRAPH_VERSION": "v22.0",
        "FB_REQUEST_TIMEOUT": "30"
      }
    }
  }
}
```

> 💡 If you use a virtualenv, point `command` to the Python inside the venv (e.g. `/path/to/pagepilot-mcp/.venv/bin/python` or `...\.venv\Scripts\python.exe`) to make sure dependencies are loaded correctly.

After saving the config, **restart your MCP client** — you'll see PagePilot's 29 tools ready for your AI agent to call.

---

## 🛠️ The 29 Tools

PagePilot provides **29 MCP tools**, organized into **4 groups**:

### 1️⃣ Status & Token

- `page_status` — Check the connection status and current Page information.
- `debug_token` — Inspect token details: expiry, scopes, app ID (requires `FB_APP_ID` / `FB_APP_SECRET`).
- `exchange_long_lived_token` — Swap a short-lived token for a long-lived one (~60 days).

### 2️⃣ Posting

- `create_post` — Publish a text post to the Page.
- `create_photo_post` — Publish a post with a photo.
- `create_link_post` — Publish a post with a link (includes a preview).
- `update_post` — Update the content of an existing post.
- `delete_post` — Delete a post.
- `schedule_post` — Schedule a post for a future time.
- `get_scheduled_posts` — List posts that are pending scheduled publishing.

### 3️⃣ Reading Posts & Comments / Moderation

- `list_posts` — List the posts on the Page.
- `get_post` — Get the details of a single post.
- `get_post_permalink` — Get the public link (permalink) of a post.
- `list_comments` — List the comments on a post.
- `get_comment_replies` — Get the replies to a comment.
- `reply_to_comment` — Reply to a comment.
- `delete_comment` — Delete a comment.
- `hide_comment` — Hide a comment.
- `unhide_comment` — Unhide a comment.
- `bulk_delete_comments` — Delete multiple comments at once.
- `bulk_hide_comments` — Hide multiple comments at once.
- `filter_negative_comments` — Filter / detect negative comments.

### 4️⃣ Analytics

- `get_page_info` — Get an overview of the Page.
- `get_fan_count` — The number of fans (followers) of the Page.
- `get_post_insights` — Detailed insights for a single post.
- `get_post_reactions` — Reaction statistics for a post.
- `get_comment_count` — Count the comments on a post.
- `get_like_count` — Count the likes on a post.
- `get_share_count` — Count the shares of a post.

---

## 📂 Project Structure

```
pagepilot-mcp/
├── pagepilot/
│   ├── __init__.py
│   ├── config.py          # Read & validate environment variables (.env)
│   ├── graph_client.py    # Robust Graph API client: auto-handles network/Graph errors,
│   │                      #   supports debug_token + long-lived token exchange
│   ├── manager.py         # Business logic for all the tools
│   └── server.py          # FastMCP entry point (run: python -m pagepilot.server)
├── requirements.txt
├── .env.example
├── LICENSE
└── README.md
```

---

## 🔧 Environment Variables

Set these in your `.env` file (copy from `.env.example`):

- `FB_PAGE_ACCESS_TOKEN` — **(required)** Page Access Token.
- `FB_PAGE_ID` — **(required)** The Fanpage's ID.
- `FB_APP_ID` — *(optional)* App ID — only needed for `debug_token` or long-lived token exchange.
- `FB_APP_SECRET` — *(optional)* App Secret — only needed for `debug_token` or long-lived token exchange.
- `FB_GRAPH_VERSION` — *(optional)* Graph API version, defaults to **`v22.0`**.
- `FB_REQUEST_TIMEOUT` — *(optional)* Per-request timeout (seconds), defaults to **`30`**.

Example `.env`:

```env
FB_PAGE_ACCESS_TOKEN=EAAB...your-token-here
FB_PAGE_ID=1234567890
FB_APP_ID=
FB_APP_SECRET=
FB_GRAPH_VERSION=v22.0
FB_REQUEST_TIMEOUT=30
```

---

## ⚠️ Disclaimer

- PagePilot is **intended only for managing Fanpages that you own or have administrative rights to**.
- You are responsible for **complying with [Facebook / Meta's Terms of Service (ToS)](https://developers.facebook.com/terms/)** and Platform Policies when using this tool.
- This tool does **not** support and does **not** encourage spam, engagement manipulation, or any policy-violating behavior.
- The author is not responsible for misuse. Please use it responsibly. 🙏

---

## 📄 License

This project is released under the **[MIT License](./LICENSE)**. You are free to use, modify, and distribute it.

---

## 👤 Author

**Thangterter-Pipo**
🔗 GitHub: [github.com/Thangterter-Pipo](https://github.com/Thangterter-Pipo)

> If PagePilot is useful to you, please ⭐ star the repo to show your support! All issues and pull requests are welcome. 💙