Telegram MCP Server — Claude Code MCP server: features & setup
Connects real Telegram user accounts to AI assistants via TDLib. Starts in read-only mode and hides write tools until configured.
claude mcp add --env TDLIB_API_ID=<TDLIB_API_ID> --env TDLIB_API_HASH=<TDLIB_API_HASH> --env TDLIB_PHONE_NUMBER=<TDLIB_PHONE_NUMBER> --env TDLIB_AUTH_CODE=<TDLIB_AUTH_CODE> --env TDLIB_2FA_PASSWORD=<TDLIB_2FA_PASSWORD> --transport stdio telegram-mcp-server -- docker run -i --rm -e TDLIB_API_ID -e TDLIB_API_HASH -e TDLIB_PHONE_NUMBER -e TDLIB_AUTH_CODE -e TDLIB_2FA_PASSWORD ghcr.io/tolboy/telegram-mcp-tdlib:1.17.3-stdioWhat Telegram MCP Server does
This server connects agents to real personal Telegram accounts via TDLib rather than a limited Bot API. On launch, it applies a read-only profile such as inbox or reader. Write actions remain invisible to the model schema until explicitly switched on.
Destructive operations like deletions or user bans require manual confirmation via host elicitation or a local loopback page. The server also uses an idempotency_key to avoid duplicate messages whenever a network reply drops.
Starting the STDIO transport manually in a terminal causes client failures. The terminal process locks td.binlog, forcing the desktop client instance to exit with code 2. Configuration requires TDLIB_API_ID and TDLIB_API_HASH.
What it helps with
- read private chats and channels with an AI assistant
- inspect recent conversations without exposure to unintended writes
- prevent duplicated outbound messages with idempotency keys
- require explicit human confirmation before deletions or bans
Example prompts for the agent
- Summarize my last 20 conversations without sending or modifying anything
- Check for unread messages across recent Telegram chats
- Search recent messages in personal Telegram dialogs
How to install Telegram MCP Server
Platform CLI
claude mcp add --env TDLIB_API_ID=<TDLIB_API_ID> --env TDLIB_API_HASH=<TDLIB_API_HASH> --env TDLIB_PHONE_NUMBER=<TDLIB_PHONE_NUMBER> --env TDLIB_AUTH_CODE=<TDLIB_AUTH_CODE> --env TDLIB_2FA_PASSWORD=<TDLIB_2FA_PASSWORD> --transport stdio telegram-mcp-server -- docker run -i --rm -e TDLIB_API_ID -e TDLIB_API_HASH -e TDLIB_PHONE_NUMBER -e TDLIB_AUTH_CODE -e TDLIB_2FA_PASSWORD ghcr.io/tolboy/telegram-mcp-tdlib:1.17.3-stdioReplace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
codex mcp add telegram-mcp-server --env TDLIB_API_ID=<TDLIB_API_ID> --env TDLIB_API_HASH=<TDLIB_API_HASH> --env TDLIB_PHONE_NUMBER=<TDLIB_PHONE_NUMBER> --env TDLIB_AUTH_CODE=<TDLIB_AUTH_CODE> --env TDLIB_2FA_PASSWORD=<TDLIB_2FA_PASSWORD> -- docker run -i --rm -e TDLIB_API_ID -e TDLIB_API_HASH -e TDLIB_PHONE_NUMBER -e TDLIB_AUTH_CODE -e TDLIB_2FA_PASSWORD ghcr.io/tolboy/telegram-mcp-tdlib:1.17.3-stdioReplace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"mcpServers": {
"telegram-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"TDLIB_API_ID",
"-e",
"TDLIB_API_HASH",
"-e",
"TDLIB_PHONE_NUMBER",
"-e",
"TDLIB_AUTH_CODE",
"-e",
"TDLIB_2FA_PASSWORD",
"ghcr.io/tolboy/telegram-mcp-tdlib:1.17.3-stdio"
],
"env": {
"TDLIB_API_ID": "<TDLIB_API_ID>",
"TDLIB_API_HASH": "<TDLIB_API_HASH>",
"TDLIB_PHONE_NUMBER": "<TDLIB_PHONE_NUMBER>",
"TDLIB_AUTH_CODE": "<TDLIB_AUTH_CODE>",
"TDLIB_2FA_PASSWORD": "<TDLIB_2FA_PASSWORD>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"servers": {
"telegram-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"TDLIB_API_ID",
"-e",
"TDLIB_API_HASH",
"-e",
"TDLIB_PHONE_NUMBER",
"-e",
"TDLIB_AUTH_CODE",
"-e",
"TDLIB_2FA_PASSWORD",
"ghcr.io/tolboy/telegram-mcp-tdlib:1.17.3-stdio"
],
"env": {
"TDLIB_API_ID": "<TDLIB_API_ID>",
"TDLIB_API_HASH": "<TDLIB_API_HASH>",
"TDLIB_PHONE_NUMBER": "<TDLIB_PHONE_NUMBER>",
"TDLIB_AUTH_CODE": "<TDLIB_AUTH_CODE>",
"TDLIB_2FA_PASSWORD": "<TDLIB_2FA_PASSWORD>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
gemini mcp add -e TDLIB_API_ID=<TDLIB_API_ID> -e TDLIB_API_HASH=<TDLIB_API_HASH> -e TDLIB_PHONE_NUMBER=<TDLIB_PHONE_NUMBER> -e TDLIB_AUTH_CODE=<TDLIB_AUTH_CODE> -e TDLIB_2FA_PASSWORD=<TDLIB_2FA_PASSWORD> telegram-mcp-server docker run -i --rm -e TDLIB_API_ID -e TDLIB_API_HASH -e TDLIB_PHONE_NUMBER -e TDLIB_AUTH_CODE -e TDLIB_2FA_PASSWORD ghcr.io/tolboy/telegram-mcp-tdlib:1.17.3-stdioReplace <…> with your own values. 2 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Telegram MCP Server
What does Telegram MCP Server do?
It connects AI clients to personal Telegram accounts via TDLib. It boots in a read-only mode that keeps write tools hidden until you enable them.
How to install Telegram MCP Server in Claude Code?
Run `claude mcp add --env TDLIB_API_ID=<TDLIB_API_ID> --env TDLIB_API_HASH=<TDLIB_API_HASH> --env TDLIB_PHONE_NUMBER=<TDLIB_PHONE_NUMBER> --env TDLIB_AUTH_CODE=<TDLIB_AUTH_CODE> --env TDLIB_2FA_PASSWORD=<TDLIB_2FA_PASSWORD> --transport stdio telegram-mcp-server -- docker run -i --rm -e TDLIB_API_ID -e TDLIB_API_HASH -e TDLIB_PHONE_NUMBER -e TDLIB_AUTH_CODE -e TDLIB_2FA_PASSWORD ghcr.io/tolboy/telegram-mcp-tdlib:1.17.3-stdio`.
Why does the server exit with code 2 on manual terminal launch?
Running the STDIO command directly in a terminal locks the td.binlog file. The AI client cannot obtain this session lock simultaneously and terminates.
