Facebook MCP server
Commit Oct 27, 2026Enables AI agents to manage Facebook Pages by posting, scheduling Reels, analyzing insights, and moderating comments via the Meta Graph API.
Also known as thenavidm/facebook-mcp-cli
- Stars
- 3
- Tools
- 18
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 27, 2026
- License
- MIT
What is Facebook MCP?
Facebook enables AI agents to manage Facebook Pages by posting, scheduling Reels, analyzing insights, and moderating comments via the Meta Graph API. It exposes 18 tools, such as list_pages, get_page, create_post.
Summary generated from the project's README
About Facebook MCP server
Managing Facebook Pages through conversational AI is what this server enables for social media managers and developers. By connecting to the Meta Graph API, it provides 18 tools that allow agents to post content, schedule Reels from local files, analyze engagement insights, and moderate comments. It works as both an MCP server for clients like Claude Desktop, Cursor, and Claude Code, and as a standalone command line interface for scripts or manual terminal use.
Setting up the server requires a Meta developer app to generate Page tokens. Once configured, the system can handle complex tasks like comparing weekly performance metrics or drafting replies to user comments. Unlike standard dashboards, this tool allows users to ask questions about their data and immediately act on the answers. Note that the server is strictly for Facebook Pages, as the API does not support personal profile posting.
What you can do with it
- 1Schedule video contentYou can instruct an AI to post a specific video file as a Reel at a designated future time.
- 2Analyze engagement trendsAsk the agent to identify which posts performed best and explain the underlying reasons.
- 3Moderate community commentsUse the agent to filter through comments to hide spam while keeping legitimate criticism visible.
- 4Automate follower growth trackingRequest a summary of follower changes over a specific period to identify peak growth days.
Written from the project's README. Every use case is checked against a quote from it.
Facebook MCP tools 18
Detected from the READMElist_pagesget_pagecreate_postcreate_photo_postpublish_draftupdate_postdelete_postlist_postslist_scheduled_postscreate_reelcreate_reel_statusget_reel_status
Show all 18 toolsShow fewer tools
list_commentsreply_to_commenthide_commentdelete_commentget_page_insightsget_post_insights
Configuration
FACEBOOK_ALLOW_WRITEFACEBOOK_APP_IDFACEBOOK_APP_SECRETFACEBOOK_PREFERRED_PAGES
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablethenavidm/facebook-mcp-cli is public and reachablegithub.com/thenavidm/facebook-mcp-cli ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-27github.com/thenavidm/facebook-mcp-cli ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model18 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubFacebook MCP Server & CLI
Facebook MCP server and CLI for Claude Code, Codex and AI agents. 18 tools for posting, Reels from a file on your machine, scheduling, drafts, Page and post insights, and comment moderation through Meta's official Graph API.
One install gives you both surfaces, the same 18 tools under the same names, built from one definition of each by Slipway, so they cannot drift apart.
Setup needs a Meta developer app. There is no way around that: Facebook only issues Page tokens through an app you own. You create one once, generate a user token, and login exchanges it for Page tokens that never expire.
Pages only. Facebook removed personal profile posting from the API in 2018 and never replaced it, so no tool can do it, including this one.
Scheduling is real. Facebook holds the post, or the Reel, and publishes it itself, so nothing has to be running on your machine at the time.
18 tools, across as many Pages as you administer.
Two ways to use it
Command line
facebook-cli runs every tool as a command. Agents that run commands, like
Claude Code, Codex and OpenCode, use it on their own, and you can type the same
commands in a terminal, a script or a cron job:
facebook-cli # every command, one line each
facebook-cli list-pages # the Pages login stored
facebook-cli get-page --json
facebook-cli list-posts --agent
facebook-cli which post a photo # find the command for a task
facebook-cli create-reel --file ~/Movies/launch.mp4 \
--caption "It's live" --publish-at 2026-11-02T15:00:00Z --confirm
facebook-cli <command> --help # what any command takes
--confirm is the shell spelling of the confirmation deleting and posting a Reel need. --json gives JSON, --compact puts it on one line, --select keeps only the fields you name, and --agent turns on all of it for a script. Exit codes are 0 ok, 1 unexpected, 2 usage or a refused write, 3 not found, 4 a token Meta refuses, 5 API, 7 rate limited and 10 no Page connected, so a script branches on the number.
facebook-cli schema <command> prints the exact JSON Schema an MCP client
receives for that tool.
MCP server, for AI agents
facebook-mcp is what Claude Code, Claude Desktop, Cursor and the rest launch.
You never run it by hand:
claude mcp add facebook -- npx -y @thenavidm/facebook-mcp-cli
In Claude Desktop, the .mcpb extension
installs on a double click. Section 5 has every other client.
What each costs
Both surfaces are the same program with the same 18 tools. The difference is when the model pays for them. Measured in Claude Code:
| MCP server | CLI | |
|---|---|---|
| Every message, with every tool loaded | 1,200 tokens, or 2,700 with writes on | nothing |
| Every message, Claude Code's default | 290 tokens, or 370 with writes on | nothing |
| When Facebook comes up | nothing more, or the tools it picks | 1,500 tokens for SKILL.md, once |
| 20 messages with Facebook in 1, every tool loaded | 24,000 tokens | 1,500 tokens |
Claude Code's tool search is on by default: it sends only the tool names and the server instructions, and loads a tool's full definition when the model reaches for it. An app that loads every tool up front pays the first line on every message, whether Facebook comes up or not. With the skill added, Claude Code also lists its one-line description, about 80 tokens.
To spend less, turn the server off when you are not using it, which in Claude
Code is the /mcp panel.
Or install the CLI and add the server on the days it earns its place.
A default install lists only the reads, which is why it costs less than one
with writes on. The figures here are 0.3.0's, with 15 tools and seven reads;
0.4.0 adds three tools (nine are listed with writes off) and has not been
measured yet. Measured on 2026-10-05 against 0.2.0, with Claude Code 2.1.286
on Claude Opus 5.5 (one short prompt with and without the server connected,
once with ENABLE_TOOL_SEARCH=false and once with the default, the difference
read from the API's own usage figures; SKILL.md the same way) and Codex
0.159.3 on gpt-6.1-sol:
| Cost | 0.2.0 | 0.3.0 |
|---|---|---|
| Claude Code, every tool loaded, every message | 3,120 | 1,176 |
| The same, with writes and deletes on | 3,108 | 2,679 |
| Claude Code's default, tool search, every message | 388 | 292 |
| The same, with writes and deletes on | 374 | 374 |
SKILL.md, read once |
1,460 | 1,451 |
| Codex over the CLI, one task, median of five | 90,223 | 71,276 |
| Codex over MCP, the same task, median of five | 37,254 | 35,254 |
The task was "find the command that reports how one post performed, and the flags it requires". 0.2.0 listed every tool and refused writes when called, so with nothing set it cost what it did with writes on. Claude Code's default with writes on is the mean of six runs a side, which ranged from 370 to 377 tokens; its other figures are means of two. Other apps and models count tokens a little differently, and tool-list characters divided by four are not API usage.
Contents
| Section | ||
|---|---|---|
| 1 | What you can ask it | Real prompts, not features |
| 2 | Quick install | One command |
| 3 | Create your Meta app | The setup step there is no way around |
| 4 | Get your token | And make it permanent |
| 5 | Connect your client | Every client, copy and paste |
| 6 | Check it worked | One command that says what is broken |
| 7 | Tools | All eighteen |
| 8 | Posting safely | Three levels, three switches |
| 9 | Several Pages | Picking which one acts |
| 10 | Limits worth knowing | What Facebook will not let you do |
| 11 | Troubleshooting | When something breaks |
| 12 | FAQ | Common questions |
1. What you can ask it 💬
- Schedule this for Tuesday at 9am, and draft two alternatives I can pick from.
- Post ~/Movies/launch.mp4 as a Reel on Friday at 6pm with this caption.
- Which post this month got the most reach, and what was different about it?
- Compare last week to the week before. Did the change in posting time help?
- Read the comments on the last five posts and tell me what people keep asking.
- Draft a reply to each comment that deserves one, in my voice. Do not post them.
- Hide the spam on that post, but leave the criticism.
- How many followers did I gain this month, and which day did most of it happen?
What this adds over Meta Business Suite, which already schedules posts:
Business Suite shows you numbers. It cannot answer a question about them. "Why did Thursday do four times better" needs someone to look at the posts, compare them, and form a view. That is the part a conversation does and a dashboard does not.
The second thing is that reading and acting happen in one place. You ask what worked, decide what to do about it, and schedule the follow-up without opening another tab or copying anything between windows.
What to do first, in order:
- Install it, one command, section 2
- Create a Meta app and connect your Page, sections 3 and 4. This is the part that takes ten minutes, and only once
- Point your client at it, section 5
- Ask it something read-only, like "how did my last five posts do"
- Turn on writing only once you trust what it is telling you
Reading works as soon as a Page is connected. Posting stays off until you set one environment variable, deliberately.
2. Quick install ⚡
npx -y @thenavidm/facebook-mcp-cli --version
Node 20 or newer. Nothing else to install.
That gets you the server. Connecting a Page is the next three sections, and it is the part that takes real time.
For the CLI as a command you or your agent can run anywhere, install it once:
npm install -g @thenavidm/facebook-mcp-cli
facebook-cli
3. Create your Meta app 🔑
Facebook has no app passwords and no personal tokens. Every credential comes through an app you own, so you make one once.
You do not need App Review, and you do not need Business Verification. Those are only for managing Pages belonging to other people, which Meta calls Advanced Access. For your own Pages, Standard Access is enough and it is granted the moment you ask.
[!TIP] One app covers Facebook, Instagram and Threads.
Use cases are ticked in a list, and you can tick several. If you plan to use more than one of these, do it now rather than making three apps and managing three sets of credentials.
Use case For Server Manage everything on your Page Facebook Pages this one Manage messaging and content on Instagram instagram-mcp Access Threads API Threads threads-mcp Incompatible combinations grey out. If an option will not tick, it conflicts with something already selected.
Step 1: the creation wizard
developers.facebook.com/apps/creation. Five screens, in this order.
App details. A name, up to 30 characters, and a contact email. The name is only shown on your own My Apps page and can be changed later.
Use cases. This is where people get stuck. The screen opens on Featured (6), and the Pages use case is not one of the six. Change the filter on the left to All (20) or Content management (5) to find it.
The featured six are Marketing API, app ads, Threads, Instant Games, Facebook Login and WhatsApp. None of those is what you want.
Business. Which business portfolio the app belongs to. An unverified one is fine, and "I don't want to connect a business portfolio yet" is a valid answer you can revisit. Verification is only needed to reach other people's data.
Requirements. For a Pages app on your own Pages this reads "No requirements identified". That is the screen confirming you do not need App Review.
Overview. Review and Create app.
Step 2: add the permissions by hand
Creating the app does not give you the permissions. This is the step every
guide skips, and without it login will fail.
Open your app, click the use case in the left sidebar, then Permissions and features. You get a table of every permission that use case can grant, and almost all of them start unadded, showing a dash in the Status column.
Click + Add on each of these:
| Permission | What it is for |
|---|---|
pages_show_list |
Seeing which Pages you administer. Without it, login finds nothing |
pages_read_engagement |
Reading posts, comments, followers and Page metadata |
pages_manage_posts |
Creating, editing and deleting posts |
pages_manage_engagement |
Replying to, hiding and deleting comments |
read_insights |
Impressions, reach and engagement numbers |
Added permissions move to Ready for testing, which is the state you want. That is Standard Access, it is immediate, and nothing is reviewed.
Those five are what this server needs. The Pages API exposes far more, covering
messaging, leads, monetization and ads, grouped by Meta into tasks like
CREATE_CONTENT, MODERATE, ANALYZE and MESSAGING. Add more only if you
have a reason, since each one widens what an agent holding the token can do.
There is also Add more to this use case in the sidebar, which widens what the use case can grant if something you need is not in the list.
[!TIP] The one people miss is
pages_read_engagement. It reads like a write permission and is not. Leave it out and reading breaks while posting still works, which is a confusing way to fail.
Step 3: make sure you have an app role
Standard Access only works for people who hold a role on the app. As its creator you are automatically an admin, so this is usually already true and worth knowing rather than doing.
It matters when it is not you. Anyone else who wants to use your app, a colleague or a second account of your own, has to be added under App roles, then Roles, as an Administrator, Developer or Tester. Without a role they cannot grant the permissions at all, and Meta's error does not say why.
Test users live in the same place. They are throwaway accounts Meta generates for you, useful for trying a destructive tool without pointing it at a real Page. They cannot administer a real Page, so they are for testing the plumbing, not the content.
Business Verification is a separate thing again, and you do not need it here. It is required for Advanced Access, which is what you would need to manage Pages belonging to people who have no role on your app. For your own Pages, Standard Access is enough.
Step 4: check the Page is in the same portfolio
Your Page must belong to the business portfolio you attached to the app, or the
app cannot see it and login reports no Pages.
Business settings, then Accounts, then Pages. If it is not listed, add it there first.
Rather have an agent do it
The steps above are written to be handed over. Paste this into Claude, or any agent with a browser:
Walk me through creating a Meta developer app for the Facebook Pages API. I need the "Manage everything on your Page" use case, Standard Access for pages_show_list, pages_read_engagement, pages_manage_posts, pages_manage_engagement and read_insights, and my Page linked to the same business portfolio. Tell me what to click, one step at a time, and wait for me to confirm each one.
4. Get your token 🔑
Generate one
- Graph API Explorer
- Pick your app, top right
- Under Permissions, add the five above
- Generate Access Token, and approve
That token dies in about an hour. It does not matter, it is used once.
Exchange it for Page tokens
npx @thenavidm/facebook-mcp-cli login <that token>
Writes ~/.facebook-mcp/pages.json, mode 600, one token per Page you
administer.
Make them permanent
Left alone, those Page tokens expire with the user token they came from. That is the single most common reason this stops working the next day.
export FACEBOOK_APP_ID=...
export FACEBOOK_APP_SECRET=...
npx @thenavidm/facebook-mcp-cli login <that token>
Both are under Settings, then Basic in your app. With them, login extends the user token first, and the Page tokens it derives never expire.
One app also covers Instagram and Threads
The same Meta app can carry the Instagram and Threads permissions. If you plan to use those too, add their products now rather than making three apps.
5. Connect your client 🔌
Claude Code
claude mcp add --transport stdio facebook -- npx -y @thenavidm/facebook-mcp-cli
With posting allowed:
claude mcp add --transport stdio --env FACEBOOK_ALLOW_WRITE=true facebook -- npx -y @thenavidm/facebook-mcp-cli
Claude Desktop
The short way: download the .mcpb extension
from the latest release and double-click it. It carries its own dependencies,
so there is no config file to edit and nothing to install first. Run login from section 4 first, and the extension uses the Pages it stored.
The long way, if you would rather edit the config yourself:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
{
"mcpServers": {
"facebook": {
"command": "npx",
"args": ["-y", "@thenavidm/facebook-mcp-cli"],
"env": { "FACEBOOK_ALLOW_WRITE": "true" }
}
}
}
Quit Claude Desktop completely and reopen it.
Cursor
~/.cursor/mcp.json for every project, or .cursor/mcp.json inside one. Same
shape as Claude Desktop.
VS Code with GitHub Copilot
.vscode/mcp.json. Note it uses servers, not mcpServers.
{
"servers": {
"facebook": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@thenavidm/facebook-mcp-cli"]
}
}
}
Windsurf, Zed, Cline, Codex CLI, Gemini CLI
All take the same stdio shape. Codex uses TOML:
[mcp_servers.facebook]
command = "npx"
args = ["-y", "@thenavidm/facebook-mcp-cli"]
Docker
docker build -t facebook-mcp .
docker run -i --rm -v facebook-mcp:/home/node/.facebook-mcp facebook-mcp
The volume matters. Page tokens live in the home directory, and without it every login is written into a container that is about to disappear.
6. Check it worked 🩺
npx @thenavidm/facebook-mcp-cli doctor
It names every Page it can reach, with follower counts. If something is wrong it says which link in the chain broke, because Meta's own error rarely does.
7. Tools 🧰
Eighteen. Each declares whether it reads or writes, so your client can show you before anything runs.
Scheduling is native: Facebook holds a scheduled post or Reel and publishes it itself, so nothing has to run on your machine at the time. Drafts are real drafts too.
Your Pages
| Tool | ||
|---|---|---|
list_pages |
read | Every Page this server can act as |
get_page |
read | Name, category, followers, about, website |
Posting
| Tool | ||
|---|---|---|
create_post |
write | Text post, optionally with a link |
create_photo_post |
write | Photo from a URL, with a caption |
publish_draft |
write | Push a draft or scheduled post out now |
update_post |
write | Edit the text of a published post |
delete_post |
delete | Cannot be undone |
list_posts |
read | Published posts with reaction, comment and share counts |
list_scheduled_posts |
read | Scheduled and draft posts not yet out |
Reels
| Tool | ||
|---|---|---|
create_reel |
write, confirmed | A Reel from a video file on this machine or a public URL: now, scheduled, or a draft |
create_reel_status |
read | The upload job create_reel started, when it outlasted the call |
get_reel_status |
read | Facebook's own status: processing, published, scheduled with its time, or the error |
Comments
| Tool | ||
|---|---|---|
list_comments |
read | With author and time |
reply_to_comment |
write | Public reply, as the Page |
hide_comment |
write | Hide or unhide. Reversible |
delete_comment |
delete | Cannot be undone |
Numbers
| Tool | ||
|---|---|---|
get_page_insights |
read | Impressions, reach, engagement, follower change |
get_post_insights |
read | How one post did |
Scheduling and drafts
create_post covers three cases with one tool:
| Intent | Arguments |
|---|---|
| Post now | message |
| Save a draft | message, draft: true |
| Schedule | message, publish_at as an ISO timestamp |
Facebook requires 10 minutes to 6 months ahead. Its own error for breaking that says nothing useful, so this checks first and tells you which rule you hit.
Reels from a file
create_reel takes file, a path on this machine, or url, a public video
Facebook fetches itself. The same three intents as a post:
| Intent | Arguments |
|---|---|
| Post now | file or url, caption |
| Save a draft | the same, draft: true |
| Schedule | the same, publish_at as an ISO timestamp |
A file goes up with Facebook's own upload, in the three phases the
Reels publishing guide
describes: start a session on the Page, send the bytes to
rupload.facebook.com, then finish with the caption and the state. If the
connection breaks partway, it asks Facebook how many bytes arrived and resumes
from there, up to three times. The file is streamed from disk, never read into
memory.
A large file takes longer than an app waits for one call, so the upload runs as
a job. The call waits 25 seconds by default, wait_seconds up to 55; if the
upload is still going, it returns a job_id to check with create_reel_status.
In a terminal the command waits to the end. Once Facebook has the video, it
processes it on its own time: get_reel_status says whether it is published,
scheduled and for when, or what stopped it.
What Facebook asks of a Reel, from the Reels publishing guide:
| Rule | Facebook's limit |
|---|---|
| Shape | 9:16. 1080x1920 recommended, 540x960 minimum |
| Length | 3 to 90 seconds |
| Frame rate | 24 to 60 frames per second |
| File | .mp4 recommended |
| Schedule | More than 10 minutes and within 29 days from now, with video_state=SCHEDULED |
| Volume | 30 API-published Reels per Page in a 24-hour moving period |
| Where | Pages only |
| Hosted URL | Not on Facebook's own CDN (fbcdn), and reachable by Facebook's crawler |
The scheduling window, the file and the URL are checked before Facebook is asked anything, so a typo costs no upload session and none of the 30. Shape, length and frame rate are checked by Facebook, and a rejection names the rule it broke.
Facebook MCP questions
What tools does Facebook MCP provide?
It exposes 18 tools, including list_pages, get_page, create_post, create_photo_post, publish_draft.
Can I use this to post to my personal Facebook profile?
No, the server only supports Facebook Pages. Facebook removed personal profile posting from the API in 2018.
Do I need to undergo App Review or Business Verification?
No, you do not need App Review or Business Verification for managing your own Pages using Standard Access.
Does scheduling require my computer to be running?
No, scheduling is handled by Facebook itself, so nothing needs to be running on your machine at the time of publication.
What is required to set up the server?
You must create a Meta developer app to obtain Page tokens.