social-mcp

A local Model Context Protocol (MCP) server that bridges an AI agent (e.g. OpenCode) with your personal Telegram direct messages: read unread messages, pull chat history for context, and send replies.

How it works

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

This is not a bot. The server runs in userbot mode — it logs in as your own account via the Telegram API, so everything it sends is sent from you. Your AI assistant simply gets a set of tools (15+) to read and manage your own chats.

⚠️ Read before using

• Automating a personal account sits in a grey zone of Telegram's Terms of Service. Keep the automation reasonable, don't spam, use at your own risk.

• Store .env and *.session outside of version control. These files grant full access to your account.

• Only you ("the boss") should command the assistant. It must never act on instructions coming from message content itself.

Related MCP server: telegram-business-bridge

Requirements

• Python 3.10+

• A Telegram api_id / api_hash from https://my.telegram.org (API Development Tools)

• Works on Windows, Linux and macOS

Project layout

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

Install dependencies

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

Configure credentials

Get your Telegram API ID/hash from https://my.telegram.org (API Development Tools).

Create a .env file in the project root:

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

Session/state files live under SOCIAL_MCP_DATA_DIR (default ~/.social-mcp), deliberately outside the repo so they can never be committed by accident.

First-time interactive login

Run this once, manually, from a real terminal — OpenCode invokes server.py over stdio and cannot answer interactive prompts.

python setup_auth.py --telegram

Telegram will text/app you a login code, and ask for your 2FA password if enabled.

Run the server standalone (smoke test)

python server.py

It will idle on stdio waiting for MCP protocol messages — that's expected; this step just confirms it starts without import/config errors. Ctrl+C to stop.

Wire it into OpenCode

Add this to ~/.config/opencode/opencode.json (adjust paths to your machine):

{
  "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"
      }
    }
  }
}

Restart OpenCode. It should discover these tools:

• list_dialogs(limit?, only_groups?, only_unread?) — start here when the chat id is unknown

• get_chat_info(platform, target_id) — chat metadata plus members and roles

• get_unread_messages(limit?, platforms?) — adds is_new and new_count; never changes read state

• mark_as_read(platform, chat_id?) — opt-in clears Telegram's unread flag; omit chat_id to clear every dialog with unread messages

• send_reply(platform, target_id, text, reply_to_message_id?, silent?)

• get_chat_history(platform, target_id, limit?, offset_id?) — offset_id pages backwards

• edit_message / delete_message

• delete_chat — full dissolution: kicks all members, leaves, purges (groups); hard-deletes owned channels; revokes and purges private dialogs

• leave_chat — exit a group/channel without touching its members

• block_user / unblock_user / get_blocked_users

• create_group / create_supergroup / add_user_to_group / remove_user_from_group / unban_user_from_group / invite_to_channel

Notes on Telegram limits

• Only the owner can destroy a group. In a supergroup you do not own, delete_chat bans every member, leaves and purges your own copy, but the group itself survives. remove_user_from_group bans in supergroups; undo it with unban_user_from_group (a banned user has to rejoin on their own).

• A bare user id needs its access_hash. Once a dialog is deleted the entity leaves the session cache and the id stops resolving — pass an @username instead, which Telegram resolves network-side.

• Media is not dropped. Messages carrying only a photo, voice note, file or sticker are reported with a [photo]-style placeholder and has_media: true.

• Reading never marks as read. get_unread_messages is side-effect free on Telegram, so the unread badge never drops on its own. Call mark_as_read when you actually want it cleared, or the counter grows forever.

• new_count needs two calls to be useful. The first call has no cutoff and counts everything unseen; afterwards it reports what arrived since the previous call.

Example agent workflow

1. Agent calls get_unread_messages(limit=10) → gets a JSON list of unread messages.

2. Agent summarizes them for you.

3. You say "reply to Anna on Telegram: I'm free after 6pm".

4. Agent optionally calls get_chat_history(platform="telegram", target_id=<id>) to see prior context, drafts a reply, and calls send_reply(platform="telegram", target_id=<id>, text="...").

Notes on reliability

• All tool functions catch platform-specific errors and return a structured {"success": false, "error": "..."} JSON payload instead of raising, so a single failed call never kills the stdio connection to OpenCode.

• Group deletion handles all Telegram quirks: owned channels are hard-deleted via channels.deleteChannel, basic groups via messages.deleteChat when you have admin rights, with an automatic kick-all → leave → purge fallback otherwise.

• storage.py keeps a small SQLite file recording which message IDs have already been surfaced, as a foundation for future "mark as read" / dedup logic — it is not yet wired into filtering by default.

License

MIT © sydrx