tdlib-mcp-server

Open-source MCP server that connects AI agents to Telegram via the official TDLib (Telegram Database Library).

Unlike other Telegram MCP servers (GramJS, Telethon), this uses the official C++ library via Python ctypes. Your account is treated as an official client (like Telegram Desktop) — no unofficial client flags.

Features

Tool	Description
get_me	Get current authorized user profile
list_dialogs	List chats with basic info
resolve_username	Convert @username to chat info
get_chat_info	Get detailed chat/channel/group info
list_messages	Get messages from a chat (newest first)
get_message	Get a single message by ID
search_in_chat	Search messages in a specific chat
search_global	Search messages across all chats

Quick Start

# 1. Clone
git clone https://github.com/Crocodile-beep/tdlib_mcp_server.git
cd tdlib_mcp_server

# 2. Create venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 3. Configure API credentials
cp .env.example .env
# Edit .env with your api_id, api_hash from https://my.telegram.org/apps

# 4. First-time auth
python test_auth.py
# Enter the code sent to Telegram

# 5. Run MCP server
python main.py

MCP Client Configuration

Add to your opencode.jsonc:

{
  "mcp": {
    "tdlib": {
      "type": "local",
      "command": ["./venv/bin/python", "-u", "./main.py"],
      "enabled": true
    }
  }
}

For other MCP clients (Claude Desktop, etc.), point them to python /path/to/tdlib-mcp-server/main.py.

Architecture

┌──────────────┐    queue.Queue     ┌──────────────────┐
│  asyncio     │ ──────────────────>│  TDLib Thread    │
│  MCP Server  │                    │  libtdjson.so    │
│  (main.py)   │ <──────────────────│  (tdlib_client)  │
│              │   asyncio.Future   │                  │
└──────────────┘                    └──────────────────┘

• Python 3.14 — MCP stdio transport via mcp SDK
• TDLib 1.8.57 — compiled libtdjson.so in lib/
• ctypes — direct C function calls, no bindings
• SQLite — session data stored in data/tdlib/ (managed by TDLib)

Roadmap

• list_messages_date_range — filter messages by date
• Error handling — FLOOD_WAIT retry, reconnection
• More tools as needed

License

MIT — fully open source, use it freely.