io.github.lanternrow/facebook-pages-mcp
Facebook Pages organic analytics, post management, and insights via Meta Graph API v25.0.
Open source Open in the app JSON README (API)
About
Facebook Pages organic analytics, post management, and insights via Meta Graph API v25.0.
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- lanternrow
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.3
- Last push
- 2026-06-29T04:14:18Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:00:22
- Updated
- 2026-08-29 04:00:22
- Origin id
io.github.lanternrow/facebook-pages-mcp
README
# facebook-pages-mcp
[](https://www.npmjs.com/package/facebook-pages-mcp)
[](https://opensource.org/licenses/MIT)
MCP server for **Facebook Pages** organic analytics and management, powered by Meta Graph API **v25.0**.
Built for [Claude Code](https://claude.ai/claude-code) and any MCP-compatible AI tool. Gives your AI assistant direct access to your Facebook Page data — posts, insights, comments, and more.
Part of **[The SEO Engine](https://lanternrow.com/seo-engine/)** toolkit by [Rex Jones](https://rexjones.me) — AI-powered SEO and social media tooling for agencies and businesses.
## Why this exists
- **No good Facebook Pages MCP server existed.** Instagram has several. Facebook Pages had none that worked on a current API version.
- **Meta deprecated legacy metrics on June 15, 2026.** `page_impressions`, `page_reach`, and `page_impressions_unique` no longer return data. This server uses the replacement metrics from day one.
- **Business Manager support.** Most businesses manage Pages through Meta Business Manager, not personal accounts. This server works with both.
## Quick start
### Option 1: npx (no install)
```json
{
"mcpServers": {
"facebook-pages": {
"command": "npx",
"args": ["-y", "facebook-pages-mcp"],
"env": {
"FB_PAGE_ACCESS_TOKEN": "your_page_access_token",
"FB_PAGE_ID": "your_page_id"
}
}
}
}
```
### Option 2: Clone and build
```bash
git clone https://github.com/lanternrow/facebook-pages-mcp.git
cd facebook-pages-mcp
npm install
npm run build
```
Then add to your Claude Code MCP settings:
```json
{
"mcpServers": {
"facebook-pages": {
"command": "node",
"args": ["/path/to/facebook-pages-mcp/dist/index.js"],
"env": {
"FB_PAGE_ACCESS_TOKEN": "your_page_access_token",
"FB_PAGE_ID": "your_page_id"
}
}
}
}
```
## Getting your Page Access Token
### Step 1: Create a Meta App
1. Go to [Meta for Developers](https://developers.facebook.com/apps/) and click **Create App**
2. Name your app and choose the **"Manage everything on your Page"** use case
3. Connect it to your Business Portfolio
### Step 2: Generate a token in the Graph API Explorer
1. Open the [Graph API Explorer](https://developers.facebook.com/tools/explorer/)
2. Select your app from the **Meta App** dropdown
3. Add permissions: `pages_show_list`, `pages_read_engagement`, `business_management`
4. Click **Generate Access Token** and complete the OAuth flow
5. When asked about Pages, select **"Opt in to all current and future Pages"**
### Step 3: Get your Page Access Token
**If your Pages are managed through Business Manager** (most businesses):
```
# First, find your business ID
GET /me/businesses?fields=id,name
# Then get Page tokens for that business
GET /{business-id}/owned_pages?fields=id,name,access_token
```
**If your Pages are on your personal account:**
```
GET /me/accounts?fields=id,name,access_token
```
Copy the `access_token` and `id` for the Page you want.
### Step 4: Exchange for a long-lived token (recommended)
Short-lived tokens expire in ~1 hour. Exchange for a long-lived token (~60 days):
```
GET /oauth/access_token
?grant_type=fb_exchange_token
&client_id={your-app-id}
&client_secret={your-app-secret}
&fb_exchange_token={short-lived-token}
```
> **Tip:** For Pages you admin, Page tokens derived from a long-lived User Token never expire.
## Tools
### Read tools
| Tool | Description |
|------|-------------|
| `get_page_info` | Page metadata: name, category, follower count, contact info, cover photo |
| `get_page_insights` | Page-level analytics with date ranges and period aggregation (day/week/28-day) |
| `get_published_posts` | Paginated list of posts authored by the Page |
| `get_post_insights` | Per-post engagement: impressions, clicks, reactions by type |
| `get_post_comments` | Paginated comments with author info and like/reply counts |
| `get_video_insights` | Video performance: views, watch time, reactions |
| `get_page_feed` | Full feed including visitor posts |
### Write tools
| Tool | Description |
|------|-------------|
| `create_post` | Publish text, link, or photo posts to the Page |
### Utility tools
| Tool | Description |
|------|-------------|
| `refresh_token_info` | Check token validity, expiration, and granted scopes |
## Metrics and the June 2026 deprecation
Meta deprecated these page-level metrics on June 15, 2026:
| Deprecated | Replacement |
|-----------|-------------|
| `page_impressions` | `page_views_total` |
| `page_reach` | Page Viewer metric (rolling out) |
| `page_impressions_unique` | Media Viewers metric (rolling out) |
This server uses only non-deprecated metrics: `page_views_total`, `page_fans`, `page_fan_adds`, `page_fan_removes`, `page_actions_post_reactions_total`.
## Architecture
```
src/
index.ts # MCP server entry point, tool registration
client.ts # Graph API HTTP client (native fetch, no dependencies)
types.ts # TypeScript interfaces for API responses
tools/
pages.ts # get_page_info, get_page_feed
insights.ts # get_page_insights, get_video_insights
posts.ts # get_published_posts, get_post_insights, get_post_comments, create_post
utils.ts # refresh_token_info
```
- **Zero external HTTP dependencies** — uses Node 18+ native `fetch`
- **Rate limit tracking** — captures `x-app-usage` and `x-page-usage` headers
- **Cursor-based pagination** — all list endpoints support `after` cursor and configurable limits
- **Zod validation** — all tool inputs validated with descriptive error messages
## Environment variables
| Variable | Required | Description |
|----------|----------|-------------|
| `FB_PAGE_ACCESS_TOKEN` | Yes | Long-lived Page Access Token |
| `FB_PAGE_ID` | Yes | Default Facebook Page ID (numeric) |
## Development
```bash
npm run dev # Watch mode — recompiles on save
npm run build # Production build
npm start # Run the server
```
## Contributing
Issues and PRs welcome. If Meta changes the API (they will), please open an issue.
## License
MIT — see [LICENSE](LICENSE).
---
Built as part of **The SEO Engine** by [Rex Jones](https://rexjones.me).