# Telegram MCP Server

Connects real Telegram user accounts to AI assistants via TDLib. Starts in read-only mode and hides write tools until configured.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 11
- Author: tolboy
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/tolboy/telegram-mcp-tdlib
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/telegram-mcp-server

## What it 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`.

## Requirements
- Needs: Docker
- Environment variables: `TDLIB_API_ID`, `TDLIB_API_HASH`, `TDLIB_PHONE_NUMBER`, `TDLIB_AUTH_CODE`, `TDLIB_2FA_PASSWORD`, `MCP_READ_ONLY`, `MCP_TOOL_PROFILE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
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-stdio
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-stdio
```
Replace <…> with your own values. 2 more environment variables are in the server README

## When to use it
- 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
- 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

## Similar
- [claude-ops-telegram-server](https://affpapa.org/en/nevibecode/mcp/claude-ops-telegram-server.md) — MCP server · ★ 547
- [tg-ws-proxy-telegram-socks5](https://affpapa.org/en/nevibecode/skills/tg-ws-proxy-telegram-socks5.md) — skill · 882 installs
- [telegram-bot](https://affpapa.org/en/nevibecode/skills/telegram-bot.md) — skill · 6200 installs
- [telegram](https://affpapa.org/en/nevibecode/skills/telegram.md) — skill · 476 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md