social-mcp

Operate the Meta suite (Facebook, Instagram, Threads) directly using Chrome Cookies. Runs entirely locally, no third-party API tokens or OAuth redirects required.

Features

Related MCP server: meta-mcp

Principle

你的 Chrome（已登入 Facebook）
    ↓ CDP (Chrome DevTools Protocol)
social-mcp 讀取 cookies
    ↓
直接 call Facebook Graph API（用 cookie session）
    ↓
完成發帖 / 讀取收件箱 / 發 IG / 發 Threads

Core Innovation: No Facebook Developer App required, no PAGE_ACCESS_TOKEN needed; it uses your real login state directly from Chrome.

Prerequisites

• Python 3.11+

• Chrome or Chromium (logged into Facebook)

• macOS / Linux

• Recommended: AIpuss-browser daemon enabled (social-mcp will automatically detect and reuse the CDP connection)

Installation

# clone 並進入目錄
git clone https://github.com/whypuss/social-mcp.git
cd social-mcp

# 用 uv 安裝（推薦）
uv sync

# 或用 pip
pip install -e .

Configuration

1. Allow Chrome to use legacy cookies (Required)

Facebook blocks "apps using legacy cookies" by default; you must enable this manually:

1. Open Facebook, click your profile picture in the top right → Settings & Privacy → Settings

2. Left menu → Security and Login

3. Scroll down to find "Allow apps to use legacy cookies"

4. Toggle to "On"

If this option is missing, your account is already allowed by default; proceed to the next step.

2. Set environment variables (Optional)

# .env 檔（放在 social-mcp/ 目錄下）
cp .env.example .env
nano .env

# Facebook 粉絲頁 ID（可從粉絲頁網址取得）
# 例如：https://www.facebook.com/MyPage → FACEBOOK_PAGE_ID=MyPage
FACEBOOK_PAGE_ID=你的頁面ID

# Instagram Business 帳號 ID（從 Meta Business Suite 取得）
IG_USER_ID=你的IG帳號數字ID

3. Confirm Chrome is logged in

Ensure your Chrome Profile 3 (named MY) is logged into Facebook and Instagram. If using the AIpuss-browser daemon, it will read this profile by default.

Usage

Start the MCP Server

# 基本啟動
uv run social-mcp

# 除錯模式（看完整日誌）
uv run social-mcp --debug

Connect to Claude Desktop

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "social": {
      "command": "uv",
      "args": ["run", "--project", "/路徑/到/social-mcp", "social-mcp"]
    }
  }
}

Restart Claude Desktop to use all the tools above in your chat.

Connect to Hermes Agent

Add to the mcp block in ~/.hermes/config.yaml, or use directly:

hermes tools enable social

Tool Usage Examples

你：幫我發一篇 Facebook 帖：「測試成功！」
Agent → post_facebook(message="測試成功！")
       → ✅ 成功！URL: https://www.facebook.com/123456789

你：讀取最新的 Messenger 訊息
Agent → get_messenger_inbox(limit=5)
       → ## Messenger 收件箱（5筆）
         1. [2026-04-24 10:00] 王小明：明天開會嗎？
         2. [2026-04-24 09:45] 李小美：收到了，謝謝！

你：回覆王大明（ID: 100001234567890）說「好的，明天見」
Agent → send_messenger(thread_id="100001234567890", message="好的，明天見")
       → ✅ 訊息已發送

About AIpuss-browser Integration

social-mcp automatically detects the AIpuss-browser daemon:

1. Reads ~/.agent-browser/default.stream to get the CDP WebSocket URL

2. Connects to the AIpuss Chrome session via WebSocket

3. Reads cookies directly from CDP (bypassing document.cookie limitations in headless mode)

Benefits:

• AIpuss's Chrome already contains your login state, no need to open another browser

• Runs entirely locally; cookies never pass through any third-party servers

• If the AIpuss daemon is not running, it will automatically fallback to launching an independent Chrome instance

Security Note

• Cookies stay local: social-mcp runs only on your machine; cookies are never sent to any third party

• No sensitive data stored: Cookies exist only in memory and disappear after the program terminates

• Recommendation: Use a dedicated Chrome Profile rather than your primary profile

Limitations and Known Issues

Development

# 安裝開發依賴
uv sync --extra dev

# 程式碼檢查
uv run ruff check social_mcp/

# 單元測試
uv run pytest

License

MIT License

Note: This tool is for personal automation purposes only. Large-scale or automated operations on Facebook/IG may violate Meta's Terms of Service; please assess the risks yourself.