Telegram MCP Server

Model Context Protocol server for Telegram. Let AI read, search, send, and forward your Telegram messages.

Quick Start

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your Telegram API credentials

# Authenticate (first time only)
npm run auth

# Build and run
npm run build
npm start

What It Does

This MCP server exposes Telegram as a set of tools that any MCP-compatible AI client can use:

Tool	Description
telegram_list_chats	List all your conversations, groups, and channels
telegram_get_me	Get info about the authenticated account
telegram_read_messages	Read message history from any chat
telegram_search_messages	Search messages across all chats
telegram_send_message	Send a message to any chat
telegram_forward_message	Forward a message between chats

Prerequisites

• Node.js 18+
• Telegram API credentials — Get them at my.telegram.org:
  1. Log in with your phone number
  2. Go to API Development Tools
  3. Create an application
  4. Copy api_id and api_hash

Configuration

Edit .env with your credentials:

API_ID=12345678
API_HASH=your_api_hash_here
SESSION_STRING=

Note: SESSION_STRING is generated automatically when you run npm run auth.

Authentication

First-time setup requires interactive login:

npm run auth

You'll be prompted for:

1. Phone number (with country code, e.g. +628123456789)
2. Auth code (sent to your Telegram app)
3. 2FA password (if enabled)

On success, your session is saved to .env automatically.

Running

Production

npm run build
npm start

Development (with hot reload)

npm run dev

Tool Reference

telegram_list_chats

List all chats (conversations, groups, channels).

Parameters:
  limit (number, optional, default: 100)
    Maximum number of chats to return

telegram_get_me

Get current authenticated user info. No parameters required.

Returns: id, firstName, lastName, username, phone

telegram_read_messages

Read messages from a specific chat.

Parameters:
  chat_id (string, required)
    Chat ID or username (e.g., "@channel", "123456789")

  limit (number, optional, default: 20)
    Number of messages to fetch

  offset_id (number, optional)
    Message ID to start from (for pagination)

telegram_search_messages

Search messages across all your Telegram chats.

Parameters:
  query (string, required)
    Search query

  limit (number, optional, default: 20)
    Maximum number of results

telegram_send_message

Send a message to any chat.

Parameters:
  chat_id (string, required)
    Chat ID or username

  text (string, required)
    Message text to send

telegram_forward_message

Forward a message from one chat to another.

Parameters:
  to_chat_id (string, required)
    Target chat ID or username

  from_chat_id (string, required)
    Source chat ID or username

  message_id (number, required)
    Message ID to forward

Example: Connect to Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["path/to/telegram-mcp/dist/index.js"]
    }
  }
}

Project Structure

telegram-mcp/
├── src/
│   ├── index.ts              # MCP server entry (stdio transport)
│   ├── auth.ts               # First-time authentication helper
│   ├── telegram-client.ts    # Telegram client wrapper
│   └── tools/
│       ├── index.ts          # Tool registry
│       ├── list.ts           # list_chats, get_me
│       ├── read.ts           # read_messages, search_messages
│       └── send.ts           # send_message, forward_message
├── .env.example              # Environment template
├── package.json
└── tsconfig.json

Tech Stack

Package	Purpose
@modelcontextprotocol/sdk	MCP protocol implementation
telegram	Telegram client (MTProto)
zod	Input validation
dotenv	Environment configuration

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

License

MIT