fast-mcp-telegram

Telegram MCP Server — Model Context Protocol (MCP) gateway for Telegram. 8 context-efficient tools, multi-tenant, MTProto bridge.

Try the Demo

1. Open https://tg-mcp.l1979.ru/setup

2. Scan the QR code from Telegram mobile (Settings → Devices → Scan QR) — no phone typing, no OTP, no 2FA. Or enter your phone number as fallback.

3. Copy your Bearer token from the success page

Then choose your path:

MCP Client (AI assistants)

• From the setup page, download the `mcp.json` file
• Add the server to your AI client and ask: "send hello to my saved messages in telegram"

Direct API (curl)

• Run the command below (replace TOKEN with yours):

curl -X POST "https://tg-mcp.l1979.ru/mtproto-api/messages.SendMessage" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params": {"peer": "me", "message": "Hello!"}}'

How It Works

This server sits between your AI agent and Telegram's API:

Your agent → MCP/HTTP → this server → MTProto → Telegram

What it does: Authenticates you with Telegram (QR or phone/bot token), exposes 8 AI-friendly tools instead of 80+ micro-APIs, and bridges raw MTProto for power users. Multi-tenant — one server, many users, isolated sessions.

Features

Quick Start

1. Install and authenticate

Quickest path (remote server): Open `/setup` → scan QR → copy token (see Try the Demo).

CLI path (local stdio): Run `fast-mcp-telegram-setup` once to create a Telegram session — then `fast-mcp-telegram` serves it:

uvx --from fast-mcp-telegram fast-mcp-telegram-setup \
  --api-id="your_api_id" \
  --api-hash="your_api_hash" \
  --phone-number="+123456789"

Bot token alternative (no phone, no OTP):

Set `BOT_API_TOKEN` instead of `--phone-number`. See Installation Guide.

2. Configure MCP Client

stdio mode (local): Add to your MCP client config (e.g. `claude_desktop_config.json`) — stdio (standard input/output) is the default transport for local MCP clients:

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["fast-mcp-telegram"],
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash"
      }
    }
  }
}

http-auth mode (remote): Add to your MCP client config (e.g. `claude_desktop_config.json`):

{
  "mcpServers": {
    "telegram": {
      "url": "https://tg-mcp.l1979.ru/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Get your token by scanning the QR code on the setup page or see Installation Guide for deploying your own server.

3. Start Using

{"tool": "search_messages_globally", "params": {"query": "hello", "limit": 5}}
{"tool": "get_messages", "params": {"chat_id": "me", "limit": 10}}
{"tool": "send_message", "params": {"chat_id": "me", "message": "Hello!"}}

Deploy to Remote Server

Deploy your own MCP server on a VDS — see Installation Guide for step-by-step instructions.

Available Tools

See Tools Reference for detailed documentation with examples.

Documentation

• Installation Guide - Local setup and remote server deployment
• Tools Reference - Complete tools documentation
• MTProto Bridge - Direct API access via curl
• Contributing - Guidelines for contributors
• Security - Security features and best practices

Telemetry

Anonymous tool telemetry since v0.30.1 — heartbeat every 6h, no credentials or message content collected. Opt out with `DO_NOT_TRACK=1`. See ADR 0005.

Auth flow telemetry since v0.38.0 — atomic events during setup (phone, QR, bot token, reauthorize). Buffered flush on flow completion. See ADR 0008.

License

MIT License - see LICENSE

mcp-name: io.github.alexeyleshchenko/fast-mcp-telegram