Facebook Messenger MCP Bridge (Python)

A complete, battle-tested AI client bridge that reads and replies to Facebook Messenger using the Model Context Protocol (MCP) and a Chrome Extension.

This system bypasses Facebook's robust anti-bot protections (like the Lexical editor) to allow seamless AI interactions on your personal Messenger account.

Architecture Overview

┌─────────────────┐     MQTT (TCP/WS)    ┌──────────────────┐     stdio      ┌─────────────┐
│  Chrome Ext     │ ◄──────────────────► │  Python MCP      │ ◄─────────────► │  AI Client  │
│  (Manifest V3)  │   Broker (HiveMQ)    │  Server          │                 │  (Claude,   │
│                 │                      │                  │                 │   Cursor,   │
│  - content.js   │                      │  - fb_read       │                 │   v.v)      │
│  - background   │                      │  - fb_send       │                 │             │
└─────────────────┘                      └──────────────────┘                 └─────────────┘

Features & Breakthroughs

1. Robust Message Reading: Bypasses obfuscated DOM classes by parsing Facebook's hidden accessibility labels (aria-labels). This correctly identifies the sender, timestamp, and message text regardless of UI updates.
2. Lexical Editor Bypass: Facebook Messenger uses the Lexical framework which ignores standard DOM value injections (input.value). This extension bypasses it by:
   • Simulating a native ClipboardEvent (Paste) to inject text into the editor.
   • Using Javascript to find and trigger a physical MouseEvent on the Send button.
3. Stable Connection: Uses a persistent MQTT connection via WebSockets from a Chrome Extension Service Worker, relayed to a Python MCP server.

Installation & Setup

1. Install Python Dependencies

uv sync

2. Configure Environment

Create a .env file in the root directory with your MQTT broker details (e.g. HiveMQ):

HIVE_MQTT_HOST=your-cluster.s2.eu.hivemq.cloud
HIVE_MQTT_PORT=8883
HIVE_MQTT_USERNAME=mcp-user
HIVE_MQTT_PASSWORD=your-password
HIVE_MQTT_CLIENT_ID=mcp-server-001

3. Load Chrome Extension

1. Open Chrome and navigate to chrome://extensions/
2. Enable Developer mode (top right toggle)
3. Click Load unpacked
4. Select the chrome-extension folder in this project.
5. Make sure you are logged into https://www.messenger.com.

4. Start the MCP Server

You can run the standalone server script to initialize both the WS-MQTT bridge and the MCP server:

uv run python start.py

5. Using with an AI Client (Cursor / Claude Desktop)

Add the following to your MCP client configuration:

{
  "mcpServers": {
    "facebook-messenger": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_server.server"],
      "env": {}
    }
  }
}

Available MCP Tools

Tool	Description
fb_list_conversations	List recent Messenger conversations to get thread_ids.
fb_read_messages	Read message history from a specific thread_id.
fb_send_message	Send a text message to a thread_id (uses Paste + Click simulation).
fb_search_contacts	Search your Messenger contacts by name.
fb_get_thread_info	Get metadata about a conversation.

Security & Disclaimer

⚠️ Important: This tool uses DOM scraping and simulated user input.

• It operates using your actual logged-in session.
• Facebook may change their UI or anti-bot measures at any time.
• Use responsibly to avoid rate limits or account blocks.
• This project is not affiliated with or endorsed by Meta/Facebook.