# Facebook MCP Server

This project is a **MCP server** for automating and managing interactions on a Facebook Page using the Facebook Graph API. It exposes tools to create posts, moderate comments, fetch post insights, and filter negative feedback — ready to plug into Claude, or other LLM-based agents.

[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/HagaiHen/facebook-mcp-server)](https://archestra.ai/mcp-catalog/hagaihen__facebook-mcp-server)
<a href="https://glama.ai/mcp/servers/@HagaiHen/facebook-mcp-server">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@HagaiHen/facebook-mcp-server/badge" />
</a>

---

## 🤖 What Is This?

This MCP provides a suite of AI-callable tools that connect directly to a Facebook Page, abstracting common API operations as LLM-friendly functions.

### ✅ Benefits

- Empowers **social media managers** to automate moderation and analytics.
- Seamlessly integrates with **Claude Desktop or any Agent client**.
- Enables fine-grained control over Facebook content from natural language.

---

## 📦 Features

| Tool                             | Description                                                         |
|----------------------------------|---------------------------------------------------------------------|
| `post_to_facebook`               | Create a new Facebook post with a message.                          |
| `reply_to_comment`               | Reply to a specific comment on a post.                              |
| `get_page_posts`                 | Retrieve recent posts from the Page.                                |
| `get_post_comments`              | Fetch comments on a given post.                                     |
| `delete_post`                    | Delete a specific post by ID.                                       |
| `delete_comment`                 | Delete a specific comment by ID.                                    |
| `hide_comment`                   | Hide a comment from public view.                         |
| `unhide_comment`                 | Unhide a previously hidden comment.                      |
| `delete_comment_from_post`       | Alias for deleting a comment from a specific post.                  |
| `filter_negative_comments`       | Filter out comments with negative sentiment keywords.               |
| `get_number_of_comments`         | Count the number of comments on a post.                             |
| `get_number_of_likes`            | Count the number of likes on a post.                                |
| `get_post_impressions`           | Get total impressions on a post.                                    |
| `get_post_impressions_unique`    | Get number of unique users who saw the post.                        |
| `get_post_impressions_paid`      | Get number of paid impressions on the post.                         |
| `get_post_impressions_organic`   | Get number of organic impressions on the post.                      |
| `get_post_engaged_users`         | Get number of users who engaged with the post.                      |
| `get_post_clicks`                | Get number of clicks on the post.                                   |
| `get_post_reactions_like_total`  | Get total number of 'Like' reactions.                               |
| `get_post_top_commenters`        | Get the top commenters on a post.                                   |
| `post_image_to_facebook`         | Post an image with a caption to the Facebook page.                  |
| `send_dm_to_user`                | Send a direct message to a user.                                    |
| `update_post`                    | Updates an existing post's message.                                 |
| `schedule_post`                  | Schedule a post for future publication.                     |
| `get_page_fan_count`             | Retrieve the total number of Page fans.                     |
| `get_post_share_count`           | Get the number of shares on a post.                         |
| `get_post_reactions_breakdown`   | Get all reaction counts for a post in one call.              |
| `bulk_delete_comments`           | Delete multiple comments by ID.                              |
| `bulk_hide_comments`             | Hide multiple comments by ID.                               |
| `bulk_unhide_comments`           | Unhide multiple comments by ID.                             |
| `get_comment_replies`            | Get all replies to a specific comment.                      |
| `get_post_permalink`             | Get the permalink URL of a post.                            |
| `get_scheduled_posts`            | List all scheduled (unpublished) posts on the Page.         |
| `get_page_info`                  | Get extended Page details (name, about, category, website). |

---

> **This fork** runs the server over **HTTP (streamable-http) in Docker**, designed for LAN/Tailscale
> access. Unlike upstream, the server holds **no credentials** — each client sends its Facebook
> `access token` + `page id` per request via HTTP headers. Original stdio project:
> [hagaihen/facebook-mcp-server](https://github.com/hagaihen/facebook-mcp-server).

## 🚀 Deploy with Docker Compose

```bash
git clone git@github.com:hoangvantuan/fb_page_mcp.git
cd fb_page_mcp
docker compose up -d --build
```

Service `fb-mcp` listens on the endpoint `http://<host>:9000/mcp` (container `0.0.0.0:8000`,
published as `9000:8000`, stateless, `restart: unless-stopped`, healthcheck included).

```bash
docker compose logs -f      # xem log
docker compose ps           # trạng thái (Up healthy)
docker compose down         # dừng
```

### Architecture — credentials from the client

The server keeps no secret. `facebook_api.py` reads credentials from the current request's headers
(via the MCP SDK `request_ctx`), so every client uses its own Page:

| Header | Meaning |
|---|---|
| `X-Facebook-Access-Token` | Facebook **Page** access token |
| `X-Facebook-Page-Id`      | Facebook Page ID |

Missing either header → the tool returns a clear `Missing credentials` error (no empty API call).
`run_http.py` disables the SDK's DNS-rebinding protection so non-localhost Hosts (LAN/Tailscale IP)
are accepted.

## 🧩 Connect from Claude Code

```bash
# host has exported FACEBOOK_ACCESS_TOKEN + FACEBOOK_PAGE_ID; single quotes keep
# the secret out of the config file (Claude Code resolves ${VAR} at runtime)
claude mcp add --transport http fb-mcp http://<HOST-OR-TAILSCALE-IP>:9000/mcp \
  --header 'X-Facebook-Access-Token: ${FACEBOOK_ACCESS_TOKEN}' \
  --header 'X-Facebook-Page-Id: ${FACEBOOK_PAGE_ID}'
```

Verify: `claude mcp list` shows `fb-mcp` connected → call `get_page_info`.

### Getting the credentials

Get a **Page Access Token** (not a User token) + **Page ID** from
<https://developers.facebook.com/tools/explorer> (choose **Get Page Access Token**), granting
`pages_show_list`, `pages_read_engagement`, `pages_manage_posts`, `pages_manage_engagement`,
`read_insights`, and `pages_messaging`. `GET /me?fields=id` with the Page token returns the Page ID.

## ⚠️ Security note

No application-level auth. Anyone who can reach port `9000` **and** holds a valid token can call every
tool. Use only on a trusted LAN/tailnet. To tighten: bind `ports` to a single host IP
(`"192.168.x.x:9000:8000"`), firewall the port, or add a reverse proxy checking a bearer token.

---

## 🤝 Contributing

Contributions, issues, and feature requests are welcome!  
Feel free to fork the repo and submit a pull request.

- Create a branch: `git checkout -b feature/YourFeature`
- Commit your changes: `git commit -m 'feat: add new feature'`
- Push to the branch: `git push origin feature/YourFeature`
- Open a pull request 🎉