🚀 PagePilot MCP

🌐 Language / Ngôn ngữ: English · Tiếng Việt

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

---

📑 Table of Contents

• Introduction
• Key Features
• Why Is It Safe?
• Requirements
• Getting a Facebook Token
• Installation & Running
• MCP Client Configuration
• The 29 Tools
• Project Structure
• Environment Variables
• Disclaimer
• License
• 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 → 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

# 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):

{
  "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:

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) 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. You are free to use, modify, and distribute it.

---

👤 Author

Thangterter-Pipo 🔗 GitHub: 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. 💙