Skip to main content
Glama
leshchenko1979

Fast MCP Telegram

by leshchenko1979
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Python Version License: MIT Docker Ready Health Status Glama Score

Fast MCP Telegram Server — MCP/HTTP Gateway for Telegram — Multi-tenant, MTProto User API, 8 context-efficient tools mcp-name: io.github.leshchenko1979/fast-mcp-telegram

Try the Demo

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

  2. Copy your Bearer token from the setup page

Then choose your path:

MCP Client (AI assistants)

  • 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!"}}'

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; session isolation and LRU cache

: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: Web Setup Interface

Browser-based authentication flow with immediate config generation

:label: One Agent, Multiple Accounts

Optional PREFIX_MCP_TOOLS_WITH_ACCOUNT — when one agent uses several MCP connections (same server, different tokens), prefixes tool names so they do not collide; not needed for standard multi-user hosting

:rocket: MTProto Proxy Support

Connect via MTProto proxy with automatic Fake TLS (EE prefix) and standard proxy detection

:card_file_box: Unified Session Management

Single configuration system for setup and server; per-token session files on shared multi-user hosts

:mag_right: Intelligent Search

Global & per-chat message search with multi-query support and intelligent deduplication

:mag: Unified Message API

Single get_messages tool for search, browse, read by IDs, and replies - 5 modes in one

:speech_balloon: Universal Replies

Get replies from channel posts, forum topics, or any message with one parameter

:busts_in_silhouette: Smart Contact Discovery

Search users, groups, channels with uniform entity schemas, forum detection, profile enrichment

:file_folder: Folder Filtering

Filter chats by dialog folder (archived, custom folders) with integer ID or name matching

:envelope: Advanced Messaging

Send, edit, reply, post to forum topics, formatting, file attachments, and phone number messaging

:paperclip: Secure File Handling

Rich media sharing with SSRF protection, size limits, album support, optional HTTP attachment streaming

:microphone: Voice Transcription

Automatic speech-to-text for Premium accounts with parallel processing and polling

:zap: High Performance

Async operations, parallel queries, and memory-conscious batching

:shield: Production Reliability

Auto-reconnect, configurable logging, comprehensive error handling

Quick Start

1. Install and authenticate

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

Sessions are stored in ~/.config/fast-mcp-telegram/.

Bot token alternative: Set BOT_API_TOKEN instead of --phone-number to skip OTP. See Installation Guide.

2. Configure MCP Client

stdio mode (local):

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

http-auth mode (remote): See Installation Guide for deploying your own server and authenticating via web interface.

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), 5 modes

send_message

Send new message

File attachments (URLs/local), formatting (markdown/html), reply to forum topics

edit_message

Edit existing message

Text formatting, preserves message structure

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, enriched data

send_message_to_phone

Message phone numbers

Auto-contact management, optional cleanup, file support

invoke_mtproto

Direct Telegram API access

Raw MTProto methods, entity resolution, safety guardrails

See Tools Reference for detailed documentation with examples.

HTTP-MTProto Bridge

Direct curl access to any Telegram API method — available for programmatic integration.

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 from curl!"}}'

Supports any Telegram method, automatic entity resolution, and TL object construction.

Integration examples:

  • CI/CD: send deploy notifications to Telegram channels

  • Monitoring: push alerts and system metrics to admin groups

  • Webhooks: receive external events and forward to Telegram

  • Backup: export chat history to external storage systems

  • Custom bots: extend functionality with external services

See MTProto Bridge for full documentation.

Documentation

License

MIT License - see LICENSE

Install Server
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
2hResponse time
3dRelease cycle
79Releases (12mo)
Commit activity
Issues opened vs closed

Resources

Tools

Related MCP Connectors

  • telegram-mcp

    Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.

  • gainium-mcp

    MCP server for Gainium — manage trading bots, deals, and balances via AI assistants

  • excalibur-mcp

    FastMCP server for posting formatted content to X (Twitter) — Tollbooth-monetized, DPYC-native

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/leshchenko1979/fast-mcp-telegram'

If you have feedback or need assistance with the MCP directory API, please join our Discord server