# 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

```bash
uv sync
```

### 2. Configure Environment

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

```env
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:
```bash
uv run python start.py
```

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

Add the following to your MCP client configuration:

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