telegram-mcp

A minimal MCP server for Telegram bot interaction via MTProto — intentionally simple, easy to read, and easy to extend.

Looking for a full-featured Telegram MCP server? Check out chigwell/telegram-mcp — 60+ tools covering messaging, groups, contacts, media, admin, and more.

This project takes a different approach: two tools, ~150 lines of server code, zero complexity. It's a clean starting point for anyone who wants to understand how MCP servers work with Telegram, or who only needs basic bot messaging without the overhead of a full client.

Why this exists

• Learning reference — Read the entire server in 5 minutes
• Fork-friendly — Add exactly the tools you need, nothing you don't
• Minimal dependencies — Just Telethon, MCP SDK, and python-dotenv

Tools

Tool	Description
send_message	Send a message to a Telegram bot and wait for its reply
get_history	Get message history with a Telegram bot

Setup

1. Get Telegram API credentials

1. Go to https://my.telegram.org/apps
2. Log in with your phone number
3. Create a new application (any name/description)
4. Copy the API ID and API Hash

2. Install and authenticate

# Install
pip install git+https://github.com/tensakulabs/telegram-mcp.git

# Set your credentials
export TELEGRAM_API_ID=12345678
export TELEGRAM_API_HASH=abcdef1234567890abcdef1234567890
export TELEGRAM_PHONE=+15551234567

# Run one-time authentication (sends a code to your Telegram app)
telegram-mcp-auth

3. Configure your MCP client

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/tensakulabs/telegram-mcp.git", "telegram-mcp"],
      "env": {
        "TELEGRAM_API_ID": "your-api-id",
        "TELEGRAM_API_HASH": "your-api-hash",
        "TELEGRAM_SESSION_DIR": "/path/to/session/dir"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/tensakulabs/telegram-mcp.git", "telegram-mcp"],
      "env": {
        "TELEGRAM_API_ID": "your-api-id",
        "TELEGRAM_API_HASH": "your-api-hash",
        "TELEGRAM_SESSION_DIR": "/path/to/session/dir"
      }
    }
  }
}

Local development

If you've cloned the repo:

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": ["--directory", "/path/to/telegram-mcp", "run", "telegram-mcp"],
      "env": {
        "TELEGRAM_API_ID": "your-api-id",
        "TELEGRAM_API_HASH": "your-api-hash"
      }
    }
  }
}

Configuration

Environment variable	Required	Default	Description
TELEGRAM_API_ID	Yes	—	Your Telegram API ID
TELEGRAM_API_HASH	Yes	—	Your Telegram API hash
TELEGRAM_PHONE	Auth only	—	Phone number for authentication
TELEGRAM_ENV_PATH	No	Auto-detect	Path to .env file
TELEGRAM_SESSION_DIR	No	Working directory	Directory for session file

How it works

This server uses the Model Context Protocol to expose Telegram interaction as tools that any MCP-compatible AI client can use. Under the hood, it:

1. Connects to Telegram via MTProto using your pre-authenticated session
2. Sends messages to bots as your user account
3. Polls for replies and returns structured JSON responses
4. Disconnects cleanly after each operation

Security notes

• Your session file (telegram_user.session) contains auth tokens — never commit it
• The .gitignore excludes session files by default
• API credentials should be passed via environment variables, not hardcoded
• This tool acts as YOUR Telegram account — treat it accordingly

Development

git clone https://github.com/tensakulabs/telegram-mcp.git
cd telegram-mcp
uv sync
uv run telegram-mcp

Requirements

• Python 3.10+
• uv (recommended) or pip

License

MIT