Fast MCP Telegram

leshchenko197949stars

Telegram MCP gateway for AI agents: 8 tools, multi-tenant HTTP/stdio, MTProto

1# Fast MCP Telegram

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher 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
License: MIT
Last checked: 2026-10-28

Stars: 49
Tools: —
Uptime: —

Tools

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

FAQ

Questions

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?

No required environment variable is listed on this record.

What transport does Fast MCP Telegram use?

Fast MCP Telegram runs locally over stdio.

When was Fast MCP Telegram last checked?

Last checked 2026-10-28. Telegram MCP gateway for AI agents: 8 tools, multi-tenant HTTP/stdio, MTProto

From the publisher

Documentation

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

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	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
:cloud: S3 Session Storage	Store sessions in S3-compatible object storage for ephemeral hosted deployments (Smithery, Fly.io, Railway)
: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
:outbox_tray: Inline File Uploads	Data: URI (base64) file uploads in `files` param — work in all transport modes, filenames preserved, images sent as photos
: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

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, PII/credential fields dropped by default (`include_sensitive=true` for raw) — 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.leshchenko1979/fast-mcp-telegram

Fast MCP Telegram

leshchenko197949stars

Telegram MCP gateway for AI agents: 8 tools, multi-tenant HTTP/stdio, MTProto

Communication Devops

Install Run on PlugMCP

GitHub Website

Run on PlugMCP

1# Fast MCP Telegram

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher 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
License: MIT
Last checked: 2026-10-28

Stars: 49
Tools: —
Uptime: —

Tools

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

FAQ

Questions

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?

No required environment variable is listed on this record.

What transport does Fast MCP Telegram use?

Fast MCP Telegram runs locally over stdio.

When was Fast MCP Telegram last checked?

Last checked 2026-10-28. Telegram MCP gateway for AI agents: 8 tools, multi-tenant HTTP/stdio, MTProto

From the publisher

Documentation

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

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

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	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
:cloud: S3 Session Storage	Store sessions in S3-compatible object storage for ephemeral hosted deployments (Smithery, Fly.io, Railway)
: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
:outbox_tray: Inline File Uploads	Data: URI (base64) file uploads in `files` param — work in all transport modes, filenames preserved, images sent as photos
: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

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, PII/credential fields dropped by default (`include_sensitive=true` for raw) — 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.leshchenko1979/fast-mcp-telegram