social-mcp

一个本地 Model Context Protocol (MCP) 服务器，将 AI 代理（例如 OpenCode）与您的个人 Telegram 直接消息连接起来：读取未读消息、拉取聊天历史以获取上下文，并发送回复。

工作原理

opencode (AI agent) ↔ social-mcp (MCP over stdio) ↔ Telethon ↔ Telegram

这不是一个机器人。服务器以 userbot 模式运行——它通过 Telegram API 以您自己的账户登录，因此它发送的所有内容都来自您。您的 AI 助手只需获得一组工具（15+）来读取和管理您自己的聊天。

⚠️ 使用前请阅读

• 自动化个人账户处于 Telegram 服务条款的灰色地带。请保持自动化合理，不要发送垃圾信息，使用风险自负。

• 将 .env 和 *.session 存储在版本控制之外。这些文件可完全访问您的账户。

• 只有您（“老板”）才能指挥助手。它绝不能根据消息内容本身中的指令采取行动。

Related MCP server: agent-telegram-mcp

要求

• Python 3.10+

• 来自 https://my.telegram.org（API 开发工具）的 Telegram api_id / api_hash

• 适用于 Windows、Linux 和 macOS

项目结构

social-mcp/
├── config.py
├── clients/
│   ├── __init__.py
│   └── telegram_client.py
├── storage.py
├── server.py
├── setup_auth.py
├── requirements.txt
└── README.md

安装依赖

python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\Activate.ps1
pip install -r requirements.txt

配置凭据

从 https://my.telegram.org（API 开发工具）获取您的 Telegram API ID/哈希。

在项目根目录创建 .env 文件：

TELEGRAM_API_ID=123456
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_PHONE=+15551234567

# Optional overrides
SOCIAL_MCP_DATA_DIR=/home/you/.social-mcp
SOCIAL_MCP_LOG_LEVEL=INFO

会话/状态文件位于 SOCIAL_MCP_DATA_DIR（默认 ~/.social-mcp）下，特意位于仓库之外，这样它们永远不会被意外提交。

首次交互式登录

在真实终端中手动运行一次——OpenCode 通过 stdio 调用 server.py，无法回答交互式提示。

python setup_auth.py --telegram

Telegram 会通过短信/应用向您发送登录代码，如果启用了 2FA，还会要求输入您的 2FA 密码。

独立运行服务器（冒烟测试）

python server.py

它将在 stdio 上空闲等待 MCP 协议消息——这是预期的；此步骤仅确认它能无导入/配置错误地启动。按 Ctrl+C 停止。

将其接入 OpenCode

将此添加到 ~/.config/opencode/opencode.json（根据您的机器调整路径）：

{
  "mcpServers": {
    "social-mcp": {
      "command": "/absolute/path/to/social-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/social-mcp/server.py"],
      "env": {
        "SOCIAL_MCP_DATA_DIR": "/home/you/.social-mcp"
      }
    }
  }
}

重启 OpenCode。它应发现以下工具：

• get_unread_messages(limit?, platforms?)

• send_reply(platform, target_id, text)

• get_chat_history(platform, target_id, limit?)

• edit_message / delete_message

• delete_chat — 完全解散：踢出所有成员、退出、清除（群组）；硬删除拥有的频道；撤销删除私人对话

• leave_chat — 退出群组/频道而不影响其成员

• block_user / unblock_user / get_blocked_users

• create_group / create_supergroup / add_user_to_group / remove_user_from_group / invite_to_channel

示例代理工作流

1. 代理调用 get_unread_messages(limit=10) → 获取未读消息的 JSON 列表。

2. 代理为您总结这些消息。

3. 您说“回复 Telegram 上的 Anna：我下午 6 点后有空”。

4. 代理可选地调用 get_chat_history(platform="telegram", target_id=<id>) 查看之前的上下文，起草回复，并调用 send_reply(platform="telegram", target_id=<id>, text="...")。

可靠性说明

• 所有工具函数都会捕获平台特定错误，并返回结构化的 {"success": false, "error": "..."} JSON 负载，而不是抛出异常，因此单个失败的调用永远不会中断与 OpenCode 的 stdio 连接。

• 群组删除处理所有 Telegram 特殊情况：拥有的频道通过 channels.deleteChannel 硬删除，基本群组在您拥有管理员权限时通过 messages.deleteChat 删除，否则自动执行踢出所有成员 → 退出 → 清除的回退方案。

• storage.py 维护一个小型 SQLite 文件，记录已呈现的消息 ID，作为未来“标记为已读”/去重逻辑的基础——目前尚未默认接入过滤。

许可证

MIT © sydrx