Telegram MCP Server for Claude Code

Read and search Telegram channel/group/DM messages directly from Claude Code.

Uses MTProto (user account API) via GramJS, so it can read full message history, not just new messages like Bot API.

Setup

1. Get Telegram API credentials

1. Go to https://my.telegram.org/apps
2. Log in with your phone number
3. Create an application
4. Note down your API ID and API Hash

2. Install and authenticate

cd telegram-mcp-server
npm install
npm run build

# Generate session (interactive, one-time)
TELEGRAM_API_ID=12345 TELEGRAM_API_HASH=abc123def456 npm run auth

This will ask for your phone number, send you a code on Telegram, and output a session string. Save it.

3. Add to Claude Code

claude mcp add telegram-mcp \
  -e TELEGRAM_API_ID=12345 \
  -e TELEGRAM_API_HASH=abc123def456 \
  -e TELEGRAM_SESSION=your_session_string_here \
  -- node /Users/kamal/Desktop/telegram-mcp-server/build/index.js

Or add manually to ~/.claude.json:

{
  "mcpServers": {
    "telegram-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/kamal/Desktop/telegram-mcp-server/build/index.js"],
      "env": {
        "TELEGRAM_API_ID": "12345",
        "TELEGRAM_API_HASH": "abc123def456",
        "TELEGRAM_SESSION": "your_session_string_here"
      }
    }
  }
}

Tools

Tool	Description
list_chats	List your chats, channels, groups with IDs and unread counts
read_messages	Read messages from a specific chat/channel/group
search_messages	Search messages globally or within a specific chat
get_chat_info	Get detailed info about a chat/channel/group
send_message	Send a message to any chat

Usage in Claude Code

Once configured, just ask Claude:

• "List my Telegram channels"
• "Read the last 50 messages from @channelname"
• "Search for 'meeting notes' across all my Telegram chats"
• "What are the recent messages in the dev group?"

Environment Variables

Variable	Required	Description
TELEGRAM_API_ID	Yes	From my.telegram.org
TELEGRAM_API_HASH	Yes	From my.telegram.org
TELEGRAM_SESSION	Yes	Generated via npm run auth