How do I install Fast MCP Telegram?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Fast MCP Telegram need an API key?

The publisher lists these environment variables: API_ID, API_HASH, SERVER_MODE, SESSION_DIR.

What transport does Fast MCP Telegram use?

Fast MCP Telegram runs locally over stdio.

When was Fast MCP Telegram last checked?

Last checked 2026-11-09. Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API

Fast MCP Telegram MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

uvx fast-mcp-telegram==0.44.1

Credentials from the publisher

API_ID — Telegram API ID from my.telegram.org
API_HASH — Telegram API Hash from my.telegram.org
SERVER_MODE — Server mode: stdio (local), http-no-auth (dev), http-auth (prod)
SESSION_DIR — Custom session directory (defaults to ~/.config/fast-mcp-telegram/)

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1API_ID=<value> API_HASH=<secret> SERVER_MODE=<value> SESSION_DIR=<value> claude mcp add io.github.alexeyleshchenko-fast-mcp-telegram -- uvx fast-mcp-telegram==0.44.1

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.alexeyleshchenko-fast-mcp-telegram": {4      "command": "uvx",5      "args": [6        "fast-mcp-telegram==0.44.1"7      ],8      "env": {9        "API_ID": "<value>",10        "API_HASH": "<secret>",11        "SERVER_MODE": "<value>",12        "SESSION_DIR": "<value>"13      }14    }15  }16}

claude_desktop_config.json

Local · pypiPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.44.1

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

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

Canonical GitHub repository: alexeyleshchenko/fast-mcp-telegram. This is the same project previously published under leshchenko1979/fast-mcp-telegram. The old GitHub URL is a public 404. Install remains pip install fast-mcp-telegram or uvx --from fast-mcp-telegram; PyPI is the stable pointer.

Try the Demo

Open https://tg-mcp.l1979.ru/setup
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.
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

Feature	Description
:building_construction: Dual Transport	Stdio for local MCP clients, HTTP for remote deploys (`http-auth` production, optional `http-no-auth` for dev)
:closed_lock_with_key: Multi-User Authentication	Shared `http-auth` server: one Bearer token per user, one Telegram account per MCP connection. QR login for instant auth — no phone/OTP/2FA.
:dart: AI-Optimized	8 consolidated tools vs 80+ micro-tools — context-efficient design, LLM-friendly API, MCP ToolAnnotations
:globe_with_meridians: HTTP-MTProto Bridge	Direct curl access to any Telegram API method with entity resolution and safety guardrails
:shield: Session ACL	Opt-in per-principal limits on `http-auth` (`ACL_ENABLED`) — chat lanes, `read_only`, `blocked_peers`, `allow_mtproto`, `ACL_DENY_UNLISTED_PRINCIPALS`; see SECURITY.md
:tv: QR & Web Setup	Scan QR from Telegram mobile for instant auth (no phone/OTP/2FA) or use phone/code/2FA fallback — live at `/setup`
:label: One Agent, Multiple Accounts

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

Tool	Purpose	Key Features
`search_messages_globally`	Search across all chats	Multi-term queries, date filtering, chat type filtering
`get_messages`	Unified message retrieval	Search/browse, read by IDs, get replies (posts/topics/messages), date filtering in all modes
`send_message`	Send new message	File attachments (URLs/local/data URIs), classic formatting (markdown/html), `parse_mode=rich` Rich Messages, reply to forum topics
`edit_message`	Edit existing message	Classic or `parse_mode=rich` formatting
`find_chats`	Find users/groups/channels	Multi-term search, contact discovery, folder filtering, username/phone lookup
`get_chat_info`	Get detailed profile info	Member counts, bio/about, online status, forum topics, common groups, enriched data
`send_message_to_phone`	Message phone numbers	Auto-contact management, optional cleanup, file support (URLs/data URIs), `parse_mode=rich`
`invoke_mtproto`	Direct Telegram API (power user)	Raw MTProto methods, entity resolution, safety guardrails — see MTProto Bridge

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