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

Go to https://my.telegram.org/apps
Log in with your phone number
Create an application
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 |

Telegram MCP Server