Facebook Web MCP

A local MCP server that lets Claude Code use your Facebook account through the normal Facebook website, in a real Chrome window you can watch.

Not a Graph API integration. There is no app id, no access token, and no password stored anywhere. Authentication is a persistent Chrome profile that you log into by hand, once.

---

Setup

Requirements: Node ≥ 20.11, Google Chrome, and an MCP client (Claude Code, Claude Desktop, or anything else that speaks MCP over stdio).

git clone https://github.com/Mrshahidali420/facebook-web-mcp.git
cd facebook-web-mcp
npm install
npm run build
claude mcp add facebook-web -- node "$PWD/dist/index.js"

Or install straight from GitHub without cloning — it compiles itself on install:

npm install github:Mrshahidali420/facebook-web-mcp
claude mcp add facebook-web -- node "$PWD/node_modules/facebook-web-mcp/dist/index.js"

Clone if you intend to fix a selector or send a pull request; the shorter form is enough if you only want to run it.

Installing this way, set FB_MCP_PROFILE_DIR to somewhere stable:

claude mcp add facebook-web \
  --env FB_MCP_PROFILE_DIR="$HOME/.facebook-web-mcp/profile" \
  -- node "$PWD/node_modules/facebook-web-mcp/dist/index.js"

Without it the profile defaults to inside node_modules/, and reinstalling or updating the package deletes your session and logs you out.

Install into a project directory, not globally. npm install -g fails on a git install: npm builds the package in a temporary clone, and for global installs it skips devDependencies, so tsc is missing and the build exits 1. A local install gets them and builds correctly.

Then just ask Claude to log you in — it calls open_facebook_login, which raises a Chrome window at Facebook and watches while you sign in. It types nothing and submits nothing; the polling exists only so it can confirm the profile was saved. If you need longer than the wait window (a 2FA code, a checkpoint), the call simply returns — the window stays open and your progress is not lost, so calling it again picks up where you were.

There is also a standalone equivalent that does not need Claude running:

npm run login

It opens a Chrome window at Facebook and then waits. You do the typing. Complete any 2FA prompt or security check in that same window. When the session goes live it confirms and exits, and the session is saved to .fb-profile/.

If Chrome is not where Playwright expects it:

npx playwright install chrome

Check the server registered:

claude mcp list          # facebook-web should report ✔ Connected

Start every session with check_facebook_session.

---

The safety model

Tools split cleanly in two.

Read-only — run immediately. check_facebook_session, open_facebook_login, search_facebook, search_groups, search_pages, open_group, search_in_group, open_page, open_post, read_post, read_comments, get_post_details, browse_feed, find_relevant_posts, draft_comment, list_pending_actions, cancel_action, selector_healthcheck.

Write — staged, never immediate. post_comment, create_post, react_to_post, share_post.

A write tool does not write. It returns a preview and a token:

ACTION:   Post a public comment on a Facebook post
TARGET:   https://www.facebook.com/groups/…/posts/…
GROUP:    UK WordPress & Web Development
AUTHOR:   Jane Smith
POSTED:   3h

THE POST YOU ARE REPLYING TO:
  Anyone know why my product pages dropped out of Google last week?

YOUR COMMENT, EXACTLY AS IT WILL BE PUBLISHED:
  Sounds like an indexing issue rather than a ranking one — worth checking
  Search Console's Pages report for "Crawled – currently not indexed".

This will be visible to everyone who can see the post, under your own name.

confirm_action(token) is the only tool in the server that changes anything.

Four things enforce that, in code rather than in prose:

Guard	What it stops
Single-use tokens	One approval can never execute twice.
Payload binding	Editing the text supersedes the old token, so text you approved is the only text that can be sent.
TTL (10 min default)	Yesterday's approval cannot fire today.
Write budget (3 per process)	A loop cannot fan out into bulk posting. It hard-fails and needs a restart.

require_confirmation: false is refused unless FB_MCP_ALLOW_UNCONFIRMED=1 is set in the server's environment. The switch lives in your environment, not in a parameter the model fills in.

It will not claim success it cannot prove

After every write, the server goes and looks:

• Comment — polls the post's comment list for your comment.
• Post — polls your feed for the published post.
• Reaction — re-reads the reaction control's state.
• Share — polls your feed for the shared post.

If it cannot confirm within the timeout, the result is status: "unverified" with what was actually observed, never "ok". "I clicked submit" and "the comment exists" are different facts and stay different all the way to Claude.

What it will not do

No CAPTCHA solving, no 2FA entry, no checkpoint clicking, no bot-detection evasion, no stealth plugins, no user-agent spoofing. There is no code path that types into a challenge — src/facebook/auth.ts only detects them and hands the browser back to you.

When Facebook signals a rate limit, the server stops and backs off. It does not retry harder.

---

Lead research

find_relevant_posts({
  group_urls: ["https://www.facebook.com/groups/wordpressuk"],
  topics: ["wordpress", "seo", "indexing", "search console"],
  posts_per_group: 30
})

Scoring is deliberately strict: a post needs both a service topic and a request-for-help signal to score well. "We migrated to WordPress last year" is discussion, not a lead. Self-promotion and already-resolved threads are scored down hard, and recency is a multiplier rather than a bonus.

Every lead carries a plain-English relevance sentence explaining its score, so the ranking can be audited rather than trusted:

{
  "post_url": "https://www.facebook.com/groups/…/posts/…",
  "group_name": "UK WordPress & Web Development",
  "score": 0.78,
  "relevance": "Asking for help (can anyone recommend); about wordpress, dropped out of google; posted in the last day; phrased as a question.",
  "matched_keywords": ["wordpress", "dropped out of google"],
  "matched_intent": ["can anyone recommend"],
  "negative_signals": []
}

Then draft_comment returns the post plus its existing comments and anti-spam guidance, you write the reply, post_comment stages it, and nothing reaches Facebook until you say so.

---

When Facebook changes its markup

It will. The design assumes it.

All DOM knowledge lives in exactly one file: src/facebook/selectors.ts. Nothing else in the project contains a CSS selector.

Each element is an ordered candidate list rather than one selector:

tier 1  ARIA role + accessible name    survives class churn and rewrites
tier 2  structural attributes          internal contracts, fairly stable
tier 3  structural relationships       shape of the tree
tier 4  visible text                   locale-dependent, last resort

The resolver records which tier actually matched. When a tier-1 candidate stops matching and extraction quietly falls through to a text heuristic, everything still works — and selector_healthcheck reports it as degraded. That is the early warning, before the last candidate dies too and tools start returning empty arrays.

A total miss throws SelectorMissError naming the strategy. It never returns null, and never an empty array that looks like "no results".

{ "posts": [], "reason": "no_posts_visible" } is a real answer and is kept distinct from a failure to read the page. Silent failure is the bug class this design refuses.

---

Layout

src/
├── index.ts              stdio server entry
├── login.ts              one-time interactive login helper
├── config.ts             env config — contains no credential fields, by design
├── logger.ts             JSONL to logs/, human lines to stderr, never stdout
├── errors.ts             typed failures carrying an instruction for the human
├── types.ts              Zod schemas for Post, Comment, Group, Page
├── browser/              session lifecycle, pacing, navigation — knows nothing about Facebook
├── facebook/
│   ├── selectors.ts      ← the only file with DOM knowledge
│   ├── resolve.ts        strategy resolver + health tracking
│   ├── auth.ts           login / challenge detection
│   ├── urls.ts           search URLs, tracking-param stripping, id extraction
│   ├── extract/          post, comment, entity, parsing helpers
│   ├── pages/            search, group, page, post, feed, home
│   └── actions/          comment, createPost, engage — each verifies afterwards
├── approvals/            token store + preview rendering
├── leads/                keyword sets and pure scoring
└── tools/                MCP tool definitions — never import Playwright

---

Configuration

Everything is optional; defaults are used with no .env at all. See .env.example for the full list. The ones worth knowing:

Variable	Default	Why you would change it
FB_MCP_MAX_WRITES	3	Raise only if you genuinely need more writes in one session.
FB_MCP_APPROVAL_TTL_MS	600000	How long a confirmation token stays valid.
FB_MCP_ALLOW_UNCONFIRMED	unset	Leave it unset.
FB_MCP_PROFILE_DIR	.fb-profile	Where the logged-in session lives.
FB_MCP_HEADLESS	false	Keep it false — headed is how you handle challenges.
FB_MCP_MIN_GAP_MS / MAX_GAP_MS	1500 / 4000	Pacing between navigations.

.fb-profile/ is your Facebook session and is gitignored. Deleting it logs you out. Never commit it, and never copy it anywhere.

---

Development

npm run typecheck
npm test           # 107 unit tests, no browser required
npm run build

Tests cover the parts where being wrong is expensive: lead scoring calibration, the approval store's four guards, the require_confirmation gate, timestamp and count parsing, and URL normalisation.

ARCHITECTURE.md covers the design in depth, and docs/facebook-dom-notes.md records what has actually been observed in Facebook's markup.

---

Contributing

Contributions are welcome — particularly selector fixes, which are the most common thing that breaks and the most useful thing to receive.

Read CONTRIBUTING.md first. It covers the three rules that are not negotiable (DOM knowledge lives in one file; writes stage rather than execute; never claim success you cannot prove) and the list of changes that will not be merged — CAPTCHA solving, bot-detection evasion, credential storage, and anything that weakens the confirmation gate.

By participating you agree to the Code of Conduct. Security issues go through SECURITY.md, never a public issue.

---

Disclaimer

This is an independent project. It is not affiliated with, endorsed by, or sponsored by Meta Platforms, Inc.

It automates a browser against a site whose terms of service restrict automated access. Using it may violate those terms and could result in your account being restricted or disabled. That risk is yours, and it is the reason the write budget, the confirmation gate, and the human-paced delays exist rather than being tunable away.

Use it on your own account. Do not use it to scrape, mass-message, harass, or impersonate anyone.

Provided without warranty of any kind — see sections 15 and 16 of the LICENSE.

---

Licence

Copyright (C) 2026 Shahid Ali

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.