mcp-telegram by dennisonbertram - MCP Server

Telegram MCP Server

A Model Context Protocol (MCP) server that provides comprehensive Telegram integration for AI assistants like Claude. This server uses the Telegram User API (not Bot API) to enable full Telegram functionality including sending messages, managing chats, and retrieving conversation history.

Features

📨 Messaging Tools

send_message - Send text messages to any Telegram chat
edit_message - Edit previously sent messages
delete_message - Delete messages from chats
forward_message - Forward messages between chats

💬 Chat Management

get_chat_list - List all your Telegram chats
get_chat_info - Get detailed information about a specific chat
search_chats - Search for chats by name or username
join_chat - Join a chat via ID or invite link
leave_chat - Leave a group or channel
create_group - Create a new Telegram group
mark_as_read - Mark messages as read in a chat

📥 Message Retrieval

get_messages - Retrieve messages from a specific chat
get_new_messages - Get messages since a specific date
get_unread_messages - Fetch unread messages across chats
get_updates - Get recent Telegram updates

👤 Account

get_me - Get information about the authenticated user

Prerequisites

Node.js 18 or higher
A Telegram account
Telegram API credentials (API ID and API Hash)

Installation

# Clone the repository
git clone https://github.com/yourusername/mcp-telegram.git
cd mcp-telegram

# Install dependencies
npm install

# Build the project (if using TypeScript)
npm run build

Quick Setup (Recommended)

The easiest way to get started is using our interactive setup:

npm run setup

This will guide you through:

Getting your Telegram API credentials
Authenticating with your phone number
Generating the configuration for Claude

Alternative Setup Methods

Web-Based Setup (Visual Interface)

npm run auth:web

Opens a web interface at http://localhost:3456 for easier authentication.

Enhanced CLI Setup (With Colors & Progress)

npm run auth

Interactive terminal setup with step-by-step guidance.

Manual Configuration

If you prefer to configure manually:

Step 1: Get Telegram API Credentials

Go to https://my.telegram.org
Log in with your phone number
Go to "API Development Tools"
Create a new application if needed
Copy your api_id and api_hash

Step 2: Set Environment Variables

Create a .env file in the project root:

TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_SESSION_STRING=your_session_string

To generate a session string, run the setup script or see the manual generation guide in docs/manual-setup.md.

Claude Code Integration

Add the Telegram MCP server to Claude Code with this single command:

claude mcp add telegram --env TELEGRAM_API_ID=your_api_id TELEGRAM_API_HASH=your_api_hash TELEGRAM_SESSION_STRING='your_session_string' -- node /absolute/path/to/mcp-telegram/src/mcp-server.js

Replace:

your_api_id with your Telegram API ID
your_api_hash with your Telegram API Hash
your_session_string with your generated session string
/absolute/path/to/mcp-telegram with the full path to this project

Claude Desktop Integration

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-telegram/src/mcp-server.js"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash",
        "TELEGRAM_SESSION_STRING": "your_session_string"
      }
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-telegram\\src\\mcp-server.js"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash",
        "TELEGRAM_SESSION_STRING": "your_session_string"
      }
    }
  }
}

After editing, restart Claude Desktop for changes to take effect.

Usage Examples

Once integrated, you can ask Claude to:

"Send a message to my friend John saying 'Hello!'"
"Show me my last 10 Telegram chats"
"Get unread messages from all my chats"
"Search for chats containing 'crypto'"
"Create a new group called 'Project Team' with users @alice and @bob"
"Delete the message with ID 12345 from chat -1001234567890"

Testing the Server

Test the MCP server directly using stdio:

# Test initialization
echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node src/mcp-server.js

# List available tools
echo '{"jsonrpc":"2.0","method":"tools/list","id":2,"params":{}}' | node src/mcp-server.js

# Call a tool (after initialization)
(echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'; 
 sleep 1; 
 echo '{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"get_me","arguments":{}}}') | node src/mcp-server.js

Troubleshooting

"Missing Telegram credentials in environment"

Ensure your .env file contains all three required variables: TELEGRAM_API_ID, TELEGRAM_API_HASH, and TELEGRAM_SESSION_STRING.

"Connection failed"

Check your internet connection
Verify your session string is valid
Try regenerating the session string

"Chat not found"

Use chat IDs with proper prefixes (e.g., -100 for channels)
For usernames, include the @ symbol
Ensure you have access to the chat

Session Expired

If your session expires, regenerate it using the generate-session.js script.

Rate Limiting

The Telegram API has rate limits. If you encounter errors, wait a few minutes before retrying.

Development

# Run tests
npm test

# Build TypeScript files
npm run build

# Watch mode for development
npm run dev

Security Notes

Never commit your .env file - It contains sensitive credentials
Keep your session string private - It provides full access to your Telegram account
Regenerate sessions periodically for security
The .gitignore file should include .env and any session files

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Add tests for new functionality
Submit a pull request

License

MIT

Support

For issues or questions, please open an issue on GitHub or contact the maintainer.