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 - Telegram integration with direct API access, powerful search, and advanced messaging for AI assistants.

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

:globe_with_meridians: HTTP-MTProto Bridge

Direct curl access to any Telegram API method with entity resolution and safety guardrails

:dart: AI-Optimized

Conserves context with fewer general-purpose tools, LLM-friendly API design, and MCP ToolAnnotations

: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

:shield: Session ACL

Opt-in per-token agent guardrails on http-auth (ACL_ENABLED) — chat lanes, read_only, empty-lane deny; see SECURITY.md

: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

:tv: Web Setup Interface

Browser-based authentication flow with immediate config generation

:building_construction: Dual Transport

Stdio for local MCP clients, HTTP for remote deploys (http-auth production, optional http-no-auth for dev)

: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 (no phone number): Create a bot via @BotFather and use --bot-api-token instead of --phone-number:

uvx --from fast-mcp-telegram fast-mcp-telegram-setup \
  --api-id="your_api_id" \
  --api-hash="your_api_hash" \
  --bot-api-token="1234567890:ABCdef..."

No OTP, no verification code. Or skip the setup step entirely — just add BOT_API_TOKEN to your env and the server auto-authenticates on startup.

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
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
4hResponse time
4dRelease cycle
55Releases (12mo)
Issues opened vs closed

Resources

Tools

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