MCP Telegram Server

MCP (Model Context Protocol) server for Telegram. Lets AI assistants (Claude, etc.) read and send Telegram messages on your behalf via MCP tools. Runs as a regular Telegram user — not a bot.

Requirements

• Java 21+
• Docker + Docker Compose
• Telegram account with API credentials from my.telegram.org

Quick Start

1. Get Telegram API credentials

Go to my.telegram.org → API development tools → create an app. You'll get api_id and api_hash.

2. Configure environment

cp .env.example .env

Edit .env:

TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_PHONE=+79001234567

POSTGRES_PASSWORD=strong_password
REDIS_PASSWORD=strong_password
MCP_PASSWORD=strong_password
MCP_ADMIN_PASSWORD=strong_password

3. Build and start

docker-compose up -d --build

4. Authorize Telegram (first run only)

On first start, TDLib needs a confirmation code sent to your phone. Pass it via environment variable — no interactive input needed:

# First run: TDLib sends code to your phone
docker-compose up app
# Wait for "AuthorizationStateWaitCode" in logs, then Ctrl+C

# Re-run with the code (and 2FA password if enabled)
docker-compose run --rm -e TELEGRAM_AUTH_CODE=12345 -e TELEGRAM_AUTH_PASSWORD=yourpassword app
# Wait for "TDLib: authorized successfully", then Ctrl+C

# Start in background — session is saved, no re-auth needed
docker-compose up -d app

Session is saved in a Docker volume — you won't need to re-authorize on restart.

5. Verify

curl -u mcp:your_mcp_password -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Architecture

Telegram (MTProto)
    └── TDLib (tdlight-java)
            └── TdLibTelegramClient
                    ├── MCP Tools ──────────────── POST /mcp  ← AI client (Claude, etc.)
                    │       get_dialogs
                    │       search_dialog
                    │       get_unread_messages
                    │       get_last_messages
                    │       send_message
                    │
                    └── TelegramUpdateListener
                            └── Redis Pub/Sub
                                    └── WebSocketBroker
                                            ├── PostgreSQL (history)
                                            └── STOMP /topic/messages → Admin UI

MCP Tools API

All requests: POST /mcp with HTTP Basic Auth.

tools/list

curl -u mcp:password -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

get_dialogs

Returns list of dialogs with unread counts.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_dialogs",
    "arguments": { "limit": 50 }
  },
  "id": 2
}

Response:

[
  { "chat_id": 123456, "type": "PRIVATE", "title": "Alice", "unread_count": 3 },
  { "chat_id": -1001234, "type": "SUPERGROUP", "title": "Dev Team", "unread_count": 0 }
]

search_dialog

Search dialogs by name.

{
  "method": "tools/call",
  "params": { "name": "search_dialog", "arguments": { "query": "Alice" } }
}

get_unread_messages

All unread messages across all dialogs.

{
  "method": "tools/call",
  "params": { "name": "get_unread_messages", "arguments": {} }
}

get_last_messages

Last N messages from a dialog.

{
  "method": "tools/call",
  "params": {
    "name": "get_last_messages",
    "arguments": { "dialog_id": 123456, "count": 10 }
  }
}

send_message

Send a message to a dialog.

{
  "method": "tools/call",
  "params": {
    "name": "send_message",
    "arguments": { "dialog_id": 123456, "text": "Hello!" }
  }
}

Admin UI

Available at http://localhost:8080/admin (credentials:

... View full README on GitHub