tgmcp

MCP server that gives AI agents (Claude, Cursor, etc.) full access to your Telegram account via MTProto.

Built with gotd/td and mcp-go.

Prerequisites

Create a Telegram Application

1. Go to https://my.telegram.org and log in with your phone number
2. Click API development tools
3. Fill in the form (app title and short name can be anything)
4. Save your App api_id and App api_hash — you'll need them below

Install

go install github.com/en666ki/tgmcp@latest

Setup

1. Authenticate

Run the interactive auth flow once to create a session file (~/.mcptg/session.json):

TELEGRAM_APP_ID=12345 TELEGRAM_APP_HASH=abc123 tgmcp auth

You'll be prompted for your phone number, the verification code, and 2FA password if enabled.

2. Add to Claude Code

claude mcp add telegram \
  -s user \
  -- tgmcp \
  --transport stdio \
  --env TELEGRAM_APP_ID=12345 \
  --env TELEGRAM_APP_HASH=abc123

Or add manually to ~/.claude/settings.json:

{
  "mcpServers": {
    "telegram": {
      "command": "tgmcp",
      "env": {
        "TELEGRAM_APP_ID": "12345",
        "TELEGRAM_APP_HASH": "abc123"
      }
    }
  }
}

Tools

Dialogs

Tool	Description
list_dialogs	List chats, channels, and groups with unread counts and last message

Messages

Tool	Description
get_messages	Get message history from a chat
get_chat_summary	Get a compact plain-text summary of recent messages (token-efficient)
send_message	Send a text message
edit_message	Edit an existing message
delete_messages	Delete messages (requires confirm: true)
forward_messages	Forward messages between chats
search_messages	Search messages in a specific chat or globally

Actions

Tool	Description
mark_as_read	Mark all messages in a chat as read
get_unread_messages	Get unread messages from a specific chat or all chats

Users

Tool	Description
resolve_username	Resolve a @username to user info
get_user_info	Get user info by ID

Configuration

Variable	Required	Description
TELEGRAM_APP_ID	yes	Telegram API app ID
TELEGRAM_APP_HASH	yes	Telegram API app hash
MCPTG_SESSION_DIR	no	Session directory (default: ~/.mcptg)

License

MIT