Content
# FBEM — Facebook Extension Crawler + MCP
**Crawl/snapshot Facebook's native composer web API and publish Reels / Photos
through a Chrome extension — exposed to any agent as an MCP server.**
FBEM drives the *same internal web API a logged-in human uses on facebook.com*
(NOT the Graph API, which suppresses reach on API-published posts). It learns the
exact upload shape by **passively snapshotting** the requests you make by hand,
then **replays** that template with fresh media + fresh volatile tokens — so it is
self-healing and needs no reverse-engineering when Facebook rotates its payload.
Any MCP-capable agent (Claude Code / Claude Desktop / Cursor / …) can plug in and
call `post_reel`, `post_photos`, `switch_profile`, `get_identity`, `health`, and
`capture_status`. Adding a new tool is one file — see [CONTRIBUTING.md](CONTRIBUTING.md).
> ⚠️ **Local tool, loopback-only.** The bridge binds `127.0.0.1` and is
> unauthenticated by design. It runs on *your* machine against *your* logged-in
> browser session. Never expose it to a network. Use it only on accounts you own
> and in line with Facebook's terms.
---
## Architecture
```
any MCP agent (Claude Code / Desktop / Cursor / …)
│ stdio (MCP protocol)
▼
fbem-mcp ──HTTP(loopback :47102)──► fbem-bridge ──WS(:9224)──► Chrome extension
(FastMCP; (FastAPI + (crawler + replay,
tools/ = one file per tool) WS server) injected in-page)
│ runs inside
▼
facebook.com tab
(your live session)
```
- **`fbem-bridge`** (persistent) holds the WebSocket to the extension, serves
media over loopback, and stores captured templates. Run it once; leave it up.
- **`fbem-mcp`** (spawned by the agent) is a thin stdio layer that calls the
bridge over HTTP. Because it's separate, every agent can spawn its own MCP
process without fighting over the extension's WebSocket port.
- **Chrome extension** has three jobs, all inside the page's own context:
1. **Crawler** — monkeypatches `fetch`/`XHR` to *passively* snapshot the genuine
native upload requests when you post by hand. Never blocks or mutates them.
2. **Tokens** — scrapes fresh volatile tokens (`fb_dtsg`, `lsd`, `jazoest`, …).
3. **Replay** — reproduces a captured template with new media + fresh tokens.
## How it works: capture-then-replay
Replay is **template-driven** and only activates after one real capture per kind.
1. Start the bridge and load the extension; open a **logged-in** facebook.com tab.
2. **Post one item by hand** (a Reel, a photo/album, a page switch).
3. The crawler snapshots the real requests (the `rupload`/photo upload + the
`ComposerStoryCreateMutation` publish) and POSTs them to the bridge, which
folds them into `template.json`.
4. From then on, the matching MCP tool replays automatically — fresh video/photo,
fresh tokens, same proven shape.
When Facebook rotates its payload and replay starts failing, just **re-capture**
(repeat steps 2–3). No code change is ever required.
## Quickstart
### 1. Install
```sh
git clone https://github.com/crisng95/fbem.git FBEM && cd FBEM
python3.11 -m venv .venv
.venv/bin/pip install -e .
```
### 2. Run the bridge (leave it running)
```sh
.venv/bin/fbem-bridge # HTTP :47102 + WS :9224, loopback only
```
### 3. Load the Chrome extension
`chrome://extensions` → enable **Developer mode** → **Load unpacked** → select the
`extension/` directory. See [extension/README.md](extension/README.md). Keep a
logged-in `www.facebook.com` tab open — replay runs inside it.
### 4. Seed a template (one manual post)
With everything running, post **one** Reel (and one photo/album) by hand. Confirm:
```sh
curl -s http://127.0.0.1:47102/api/health | python3 -m json.tool
# look for: extension_connected: true, has_template: true, has_photo_template: true
```
> **Already have captured templates elsewhere?** Point the bridge at that captures
> directory and skip re-snapshotting entirely:
> ```sh
> FBEM_CAPTURES_DIR=/path/to/existing/captures fbem-bridge
> ```
### 5. Plug the MCP into your agent
**Claude Code:**
```sh
claude mcp add fbem -- /abs/path/to/FBEM/.venv/bin/fbem-mcp
```
**Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"fbem": { "command": "/abs/path/to/FBEM/.venv/bin/fbem-mcp" }
}
}
```
**Any MCP client:** run the command `fbem-mcp`, transport **stdio**.
The agent can now call the tools below. (The bridge from step 2 must stay running.)
## MCP tools
| Tool | What it does |
|------|--------------|
| `post_reel` | Publish a Reel from a local `.mp4`. Args: `video_path`, `caption`, `page_id?`, `scheduled_publish_time?`. |
| `post_photos` | Publish a photo (1 file) or album (N files) from local `.jpg/.png`. Args: `image_paths[]`, `caption`, `page_id?`, `scheduled_publish_time?`. |
| `switch_profile` | Switch the acting page/profile so later posts go out AS that page. Args: `target_id`. |
| `get_identity` | Read which page/profile the tab currently posts AS (read-only). |
| `health` | Bridge + extension health (connection, templates, tab TTL). |
| `capture_status` | Crawler/snapshot status: what's captured, what's ready to post, and exactly what to (re)snapshot if not. |
## When do I need to (re)snapshot?
- **First run / a kind never captured** → yes: post that kind once by hand.
- **Reel vs Photo vs Switch are separate templates** → capturing a Reel does not
enable photo posting; capture each kind once.
- **Already captured and working** → no. Templates persist in `FBEM_CAPTURES_DIR`.
- **Facebook rotated its payload (replay errors like `story_create=null`,
`no_template_captured`, repeated 502s)** → re-capture that one kind by hand.
Ask the agent to call `capture_status` any time — it reports exactly what's ready
and what to do.
## Configuration
All optional; sensible loopback defaults. See [.env.example](.env.example).
| Env | Default | Purpose |
|-----|---------|---------|
| `FBEM_HTTP_PORT` | `47102` | Bridge HTTP API port |
| `FBEM_WS_PORT` | `9224` | Extension WebSocket port |
| `FBEM_WS_HOST` | `127.0.0.1` | WS bind host (must be loopback) |
| `FBEM_HOME` | `~/.fbem` | Base dir for state |
| `FBEM_CAPTURES_DIR` | `$FBEM_HOME/captures` | Captured templates (contain live tokens) |
| `FBEM_MEDIA_DIR` | `$FBEM_HOME/media` | Media served to the extension |
| `FBEM_BRIDGE_URL` | `http://127.0.0.1:47102` | Where the MCP reaches the bridge |
| `FBEM_TAB_TTL_S` | `7200` | *Advanced:* tab auto-reload window (seconds) that keeps tokens fresh |
| `FBEM_TAB_ACTIVE_WINDOW_S` | `90` | *Advanced:* how recently a capture must arrive to count the tab as "active" (seconds) |
| `FBEM_PUBLISH_OP_RE` | *(built-in regex)* | *Advanced:* override the regex matching the Reel publish mutation (set only if FB renames the op) |
## Security
- **Loopback-only & unauthenticated by design.** Startup refuses a non-loopback
`FBEM_WS_HOST`. Never port-forward or proxy it.
- **Captures contain live FB tokens** (`fb_dtsg`, `lsd`, cookies). `captures/` is
git-ignored — never commit it. Treat `FBEM_CAPTURES_DIR` as a secret.
- **No tokens in code.** The callback secret is random per process; volatile FB
tokens are scraped live from the page at replay time.
## Project layout
```
fbem/
bridge/ persistent backend (FastAPI :47102 + extension WS :9224)
server.py · ws_server.py · bridge_client.py · capture_store.py · config.py · run.py
mcp/ the MCP server (any-agent pluggable)
server.py · registry.py · bridge_api.py
tools/ ONE FILE PER TOOL ← the contribution surface
_template.py · post_reel.py · post_photos.py · switch_profile.py
get_identity.py · health.py · capture_status.py
extension/ Chrome MV3 (crawler snapshot + replay)
docs/PROTOCOL.md the decoded native upload protocol
```
## Contributing
Adding a tool is one file. Copy `fbem/mcp/tools/_template.py`, write a typed async
function, done — it's auto-discovered. See **[CONTRIBUTING.md](CONTRIBUTING.md)**.
## License
[MIT](LICENSE).
