Content
# ai-cdp-browser
> Use CDP Browser Hijacking to operate mainstream social platforms - no API Token required, no developer account needed.
Through your own browser's login session, AI Agent uses CDP to take control and post, crawl, and converse.
## 2026-04-26 Test Results
| Platform | Function | Status |
|------|------|------|
| **Facebook** | Post text/image, read private messages, read notifications | ✅ Successful |
| **Instagram** | Post image (caption goes to sharing page) | ✅ Successful |
| **Threads** | Post text/image | ✅ Successful |
| **Google Trends** | HK popular topic crawler | ✅ Successful |
| **Gemini** | AI conversation, content generation | ✅ Successful |
## Principle
```
You log in once (Chromium — FacebookMCP profile)
↓
Chromium starts --remote-debugging-port=9333
↓
Playwright CDP takes control of browser
↓
Directly operate DOM (post / crawl / converse)
```
**Why not use official API?**
- Facebook Graph API can only operate fan pages, **cannot read private messages/notifications of personal accounts**
- X API requires payment to post
- Our solution: **what your account can do, AI can do**
**Why not directly launch Playwright?**
- macOS Chrome cookies use `login.keychain` encryption, external programs cannot decrypt
- By taking control of a decrypted session through CDP, bypass this limitation
## Installation
```bash
git clone https://github.com/whypuss/ai-cdp-browser.git
cd ai-cdp-browser
uv sync
```
## Settings
### 1. Create an independent Chromium profile
```bash
mkdir -p ~/Library/Application\ Support/Chromium/FacebookMCP
```
### 2. Log in to each platform
```bash
open -a Chromium --args --user-data-dir="$HOME/Library/Application Support/Chromium/FacebookMCP"
```
Log in to the browser:
- **Facebook** (only once)
- **Instagram** (only once)
- **Threads** (synchronized with Facebook login)
- **Google** (for Gemini, optional)
### 3. Start CDP Server
```bash
"/Applications/Chromium.app/Contents/MacOS/Chromium" \
--remote-debugging-port=9333 \
--user-data-dir="$HOME/Library/Application Support/Chromium/FacebookMCP" \
--profile-directory="Default" &
```
### 4. Automatic detection
`browser_hijack.py` automatically detects `9333` or `9222`, whichever has an active session.
## Usage examples
### Single-platform posting test
```bash
# Facebook text/image post
uv run python -m social_mcp.post_facebook "caption" /tmp/image.jpg
# Instagram text/image post
uv run python -m social_mcp.post_ig "caption text" /tmp/image.jpg
# Threads text/image post
uv run python -m social_mcp.post_threads "caption" /tmp/image.jpg
```
### Automatic workflow (post every 2 hours)
```bash
# Google Trends HK → Gemini generates original caption → FB + IG + Threads simultaneous posting
uv run python scripts/social_workflow.py
```
Anti-duplication logic: `posted_topics.json` records the last 12 published topics, each topic is posted only once.
### Gemini AI conversation
Use CDP to take control of Gemini webpage, direct conversation:
```python
# Input prompt on Gemini page, automatically analyze GitHub project
prompt = "Please analyze https://github.com/whypuss/ai-cdp-browser"
# → Gemini returns complete analysis report
```
## Architecture
## Skills (Hermes Agent skill library)
`skills/` directory contains browser automation skills used by Hermes Agent.
| Skill | Purpose | Core method |
|-------|------|---------|
| `instagram-workflow` | IG text/image posting | filechooser event listener upload image |
| `facebook-workflow` | FB text/image posting | base64 DataTransfer injection (React does not eat input.files) |
| `threads-composer-debug` | Threads posting | Playwright pure Selector, force=True bypass overlay |
| `facebook-mcp-browser-setup` | Chromium browser setup | ungoogled-chromium + independent profile |
Detailed documentation: [skills/README.md](skills/README.md)
## Architecture
```
ai-cdp-browser/
├── social_mcp/
│ ├── browser_hijack.py # CDP takeover core (multi-port automatic detection)
│ ├── mcp_server.py # MCP Server (Hermes Agent / Claude Desktop)
│ ├── post_facebook.py # Facebook posting (supports image, DataTransfer injection)
│ ├── post_ig.py # Instagram posting (supports image, filechooser)
│ ├── post_threads.py # Threads posting (supports image, Playwright Selector)
│ └── browser_hijack.py
├── skills/ # Hermes Agent skill library
│ ├── instagram-workflow/
│ ├── facebook-workflow/
│ ├── threads-composer-debug/
│ ├── facebook-mcp-browser-setup/
│ └── README.md
└── scripts/
└── social_workflow.py # Unified workflow: Google Trends → Gemini → three-platform automatic posting
```
## New computer recovery
Only three things are needed:
| Item | Backup/Restore |
|------|-----------|
| `Chromium.app` | `brew install --cask chromium` |
| `FacebookMCP` profile | `~/Library/Application Support/Chromium/FacebookMCP/` (copy) |
| ai-cdp-browser environment | `git clone + uv sync` |
Copy `FacebookMCP` profile, all platforms (Facebook / IG / Threads / Google) are restored, **no need to log in again**.
## Frequently Asked Questions
**Q: Will sessions expire?**
A: Facebook may require re-verification. If operation fails, log in again in the CDP Chromium window.
**Q: Does it support fan pages?**
A: Currently supports personal accounts. Fan pages require identity switching, DOM selector needs adjustment.
**Q: IG posting stuck at "Next"?**
A: `post_ig.py` has been fixed. IG new UI sometimes skips filter page directly to sharing page, script supports automatic judgment.
**Q: Can Gemini generate images?**
A: Free version does not support, need to upgrade Google AI Plus. Text conversation and content analysis are normal.
## Security
- Cookies remain local, never transmitted to third parties
- No official API used, no access token required
- Independent profile, does not affect daily browsing session
**Warning**: Large-scale automated operations may violate platform service terms, please evaluate risks yourself.
## License
MIT License
