# Facebook Web MCP

[![CI](https://github.com/Mrshahidali420/facebook-web-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Mrshahidali420/facebook-web-mcp/actions/workflows/ci.yml)
[![Licence: GPL v3](https://img.shields.io/badge/licence-GPLv3-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D20.11-brightgreen.svg)](https://nodejs.org)

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).

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
npx playwright install chrome
```

Check the server registered:

```bash
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:

```json
{
  "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

```bash
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](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](CODE_OF_CONDUCT.md).
Security issues go through [SECURITY.md](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](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/>.