Fast MCP Telegram

leshchenko1979/fast-mcp-telegram

Connects Claude to the full Telegram API so you can build agents that actually interact with Telegram beyond basic bot commands. You get access to messages, media handling, voice and video calls, polls, group management, reactions, admin operations, and search. Useful when you need an AI that can monitor channels, respond contextually in group chats, manage communities, or parse message history. Goes well beyond webhook bots since you can trigger actions from Claude's side and work with the complete platform feature set instead of just incoming messages.

GitHub stars: 50
tools: 8
auth: Secret needed
transport: STDIO, HTTP
env vars: 4
last updated: Nov 11, 2026

View on GitHub

Install

From registry metadata

$ npx add-mcp https://tg-mcp.l1979.ru/v1/mcp --name fast-mcp-telegram

Run in your terminal. add-mcp asks which agents to add it to (Claude Code, Codex, Cursor and more). Add -g to install it for every project.

Review the command, arguments and environment values before installing. MCP servers run with your local permissions.

Other ways

Claude Code

$ claude mcp add --transport http fast-mcp-telegram https://tg-mcp.l1979.ru/v1/mcp

Run in your terminal. Add --scope user to make it available in every project.

Tools

Verified live · 8 tools

Verified live against the running server on Nov 6, 2026.

search_messages_globallySearch all Telegram chats at once (not scoped to one chat). Comma-separated query terms; optional filters by date, chat kind, and public username. Results are ordered by ascending date-time (oldest first); limit selects the newest N. Success: message list and metadata dict. Gl...8 params

Search all Telegram chats at once (not scoped to one chat). Comma-separated query terms; optional filters by date, chat kind, and public username. Results are ordered by ascending date-time (oldest first); limit selects the newest N. Success: message list and metadata dict. Gl...

Parameters* required

auto_expand_batchesinteger

Extra search batches to run when filters narrow results. Higher values may return more matches at the cost of latency.default: 2

chat_typestring

Comma-separated chat kinds: private, bot, group, channel. Case-insensitive; extra spaces allowed.

include_total_countboolean

If true, response may include total_count where supported (per-chat search; ignored for global search).default: false

limitinteger

Maximum messages to return (recommended 50 or less).default: 50

max_datestring

Inclusive maximum date filter (ISO 8601 date or datetime). Omit for no upper bound.

min_datestring

Inclusive minimum date filter (ISO 8601 date or datetime). Omit for no lower bound.

publicboolean

If true, prefer chats with a public username; if false, without. Does not apply to private DMs. Omit to skip this filter.

query*string

Search terms, comma-separated for multiple terms (OR-style global search). Required.

get_messagesRead or search messages in one chat: browse latest, search text, fetch by ids, or load replies to a message (comments, forum topics, threads). Use from_user to filter by sender (server-side, per-chat only). Use context to include neighboring messages and reply chains around ea...13 params

Read or search messages in one chat: browse latest, search text, fetch by ids, or load replies to a message (comments, forum topics, threads). Use from_user to filter by sender (server-side, per-chat only). Use context to include neighboring messages and reply chains around ea...

Parameters* required

auto_expand_batchesinteger

Extra search batches to run when filters narrow results. Higher values may return more matches at the cost of latency.default: 2

chat_id*string

Target chat: numeric id (e.g. -100…), username without @, or 'me' for Saved Messages.

contextinteger

Number of surrounding messages to include as context for each search result. 0 = disabled (default). 1-10 = include N messages before and N after each result. Also fetches the message being replied...default: 0

from_userstring

Only return messages from this sender. Not a display-name or contact-name search — bare strings resolve like chat_id via get_entity (usernames are case-insensitive and may match an unrelated channe...

include_repliesboolean

If true, fetch up to 5 direct replies per search result and attach as replies. Each result costs one API call (not batchable). Default: false.default: false

include_total_countboolean

If true, response may include total_count where supported (per-chat search; ignored for global search).default: false

limitinteger

Maximum messages to return (recommended 50 or less).default: 50

max_datestring

Inclusive maximum date filter (ISO 8601 date or datetime). Omit for no upper bound.

message_idsarray

Exact message ids to fetch. Mutually exclusive with query and reply_to_id.

min_datestring

Inclusive minimum date filter (ISO 8601 date or datetime). Omit for no lower bound.

querystring

Search within this chat only; comma-separated terms. Omit to browse latest or use message_ids / reply_to_id modes.

reply_to_idinteger

Anchor message id: channel post id, forum topic_id from get_chat_info, or a message id for direct replies. Use with thread_scope.

thread_scopestring

Only with reply_to_id. auto: full forum topic (topic_id) or channel comment thread via getReplies; else direct replies. full: nested branch under a message id (forum in-topic uses search window, no...one of auto · full · directdefault: auto

send_messageSend text and optional file attachments to a Telegram chat. Supports reply-to (including forum topics and channel discussion groups), parse_mode: classic markdown/html/auto (entities) or rich (Rich Message document; dialect auto-detected). parse_mode=rich cannot be combined wi...7 params

Send text and optional file attachments to a Telegram chat. Supports reply-to (including forum topics and channel discussion groups), parse_mode: classic markdown/html/auto (entities) or rich (Rich Message document; dialect auto-detected). parse_mode=rich cannot be combined wi...

Parameters* required

chat_id*string

Target chat: numeric id (e.g. -100…), username without @, or 'me' for Saved Messages.

filesarray

List of attachment URLs, local paths, or data URIs (one or more strings). data: URIs (data:<mime>;base64,<payload>) work in all server modes; local paths work in stdio mode only.

message*string

Message text. When sending files, used as caption.

parse_modestring

'markdown'/'html'/'auto': classic entity formatting (auto detects). 'rich': Telegram Rich Message document; dialect auto-detected (known HTML tags outside code → rich HTML, else rich markdown). Def...one of markdown · html · auto · richdefault: auto

reply_to_idinteger

Telegram message id to reply to. For forums, topic root id; for channel posts, post id (may create a comment). Omit for a new top-level message.

save_as_draftboolean

If true, save the text as the chat's draft instead of sending it (an empty text clears the existing draft). User sessions only — bot accounts cannot call messages.saveDraft. Cannot be combined with...default: false

schedule_datestring

ISO 8601 instant at which Telegram should deliver the message, e.g. '2026-10-20T09:00:00Z' or '2026-10-20T12:00:00+03:00'. Must be in the future. On send: queues the message instead of delivering n...

edit_messageReplace the text of an existing message in a Telegram chat. Only works on messages sent by the authenticated account. Cannot edit media or other message attributes — text only. parse_mode: classic markdown/html/auto or rich (Rich Message; dialect auto-detected). schedule_date...5 params

Replace the text of an existing message in a Telegram chat. Only works on messages sent by the authenticated account. Cannot edit media or other message attributes — text only. parse_mode: classic markdown/html/auto or rich (Rich Message; dialect auto-detected). schedule_date...

Parameters* required

chat_id*string

Target chat: numeric id (e.g. -100…), username without @, or 'me' for Saved Messages.

message*string

Message text. When sending files, used as caption.

message_id*integer

Message id in this chat to edit (from get_messages or Telegram).

parse_modestring

schedule_datestring

find_chatsFind users/groups/channels by name, username, or phone. Comma-separated usernames are searched in parallel and results are merged round-robin. Global search (query required) searches all Telegram; with min_date, max_date, or filter, search uses dialog list or a named filter; i...7 params

Find users/groups/channels by name, username, or phone. Comma-separated usernames are searched in parallel and results are merged round-robin. Global search (query required) searches all Telegram; with min_date, max_date, or filter, search uses dialog list or a named filter; i...

Parameters* required

chat_typestring

Comma-separated chat kinds: private, bot, group, channel. Case-insensitive; extra spaces allowed.

folderstring

Telegram folder name (case-insensitive exact match after normalization). In Telegram's UI these are called folders; internally they are "dialog filters" — saved filter presets that group chats by c...

limitinteger

Maximum chats to return (recommended 50 or less).default: 20

max_datestring

Inclusive maximum date filter (ISO 8601 date or datetime). Omit for no upper bound.

min_datestring

Inclusive minimum date filter (ISO 8601 date or datetime). Omit for no lower bound.

publicboolean

If true, prefer chats with a public username; if false, without. Does not apply to private DMs. Omit to skip this filter.

querystring

Name, username (no @), phone (+country…), or comma-separated usernames for batch lookup. Example: 'alice,bob,charlie'. Required for global search unless you use min_date/max_date or folder alone.

get_chat_infoLoad profile and metadata for one user, bot, group, or channel. Success: info dict; forum chats may include topics up to topics_limit; user targets may include common_chats up to common_chats_limit. Full documentation: https://github.com/leshchenko1979/fast-mcp-telegram/blob/m...3 params

Load profile and metadata for one user, bot, group, or channel. Success: info dict; forum chats may include topics up to topics_limit; user targets may include common_chats up to common_chats_limit. Full documentation: https://github.com/leshchenko1979/fast-mcp-telegram/blob/m...

Parameters* required

chat_id*string

Target chat: numeric id (e.g. -100…), username without @, or 'me' for Saved Messages.

common_chats_limitinteger

Max common groups to list for user targets.default: 10

topics_limitinteger

Max forum topics to list when the chat is a forum.default: 20

send_message_to_phoneSend to a phone number: may create a temporary contact, then send text or files. Supports parse_mode: classic markdown/html/auto or rich (Rich Message; dialect auto-detected). parse_mode=rich cannot be combined with files. schedule_date (ISO 8601, future) queues the message in...10 params

Send to a phone number: may create a temporary contact, then send text or files. Supports parse_mode: classic markdown/html/auto or rich (Rich Message; dialect auto-detected). parse_mode=rich cannot be combined with files. schedule_date (ISO 8601, future) queues the message in...

Parameters* required

filesarray

List of attachment URLs, local paths, or data URIs (one or more strings). data: URIs (data:<mime>;base64,<payload>) work in all server modes; local paths work in stdio mode only.

first_namestring

First name when creating a temporary contact.default: Contact

last_namestring

Last name when creating a temporary contact.default: Name

message*string

Message text. When sending files, used as caption.

parse_modestring

phone_number*string

E.164 phone number with country code, e.g. +1234567890 (must be on Telegram).

remove_if_newboolean

If true, delete the contact after send when it was created only for this send.default: false

reply_to_msg_idinteger

Reply to this message id in the target chat after resolve.

save_as_draftboolean

schedule_datestring

invoke_mtprotoLow-level Telegram API (MTProto) invoke for methods not wrapped by other tools. Dangerous methods require allow_dangerous=true. Success: API result dict or normalized error. PII and credential-shaped fields (phone, access_hash) are dropped from a successful result by default;...5 params

Low-level Telegram API (MTProto) invoke for methods not wrapped by other tools. Dangerous methods require allow_dangerous=true. Success: API result dict or normalized error. PII and credential-shaped fields (phone, access_hash) are dropped from a successful result by default;...

Parameters* required

allow_dangerousboolean

If false, destructive methods (e.g. deletes) are blocked. Set true only when intended.default: false

include_sensitiveboolean

If true, return the raw result including PII and credential-shaped fields (phone, access_hash). Default false drops them.default: false

method_full_name*string

Telegram API method, e.g. "messages.GetHistory" or "users.GetFullUser" (normalization applied).

params_json*string

JSON object string of TL parameters as in Telegram API docs; nested TL uses "_": "typeName" discriminator.

resolveboolean

If true, resolve string/int peer-like fields to TL Input* entities before invoke.default: true

Configuration

API_ID*

Telegram API ID from my.telegram.org

API_HASH*secret

Telegram API Hash from my.telegram.org

SERVER_MODEdefault: stdio

Server mode: stdio (local), http-no-auth (dev), http-auth (prod)

SESSION_DIR

Custom session directory (defaults to ~/.config/fast-mcp-telegram/)

Readme

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

View the full README on GitHub

Details

Repository: github.com/leshchenko1979/fast-mcp-telegram
Website: github.com/leshchenko1979/fast-mcp-telegram
Category: Communication & Messaging
Package: fast-mcp-telegram
Transport: STDIO, HTTP
Auth: Required
Registry: MCP registry, active
Tools verified: Nov 6, 2026

Related Communication & Messaging MCP servers

View all

Slack Explorer MCPshibayu36/slack-explorer-mcpMCP server specialized in retrieving information from Slack messages and threads49stars

Outlook MCPmpalermiti/outlook-mcpMicrosoft Outlook personal accounts: mail, rules, calendar, contacts, to-do, drafts (77 tools).41stars

Slack MCP Serverjtalk22/slack-mcp-serverCatch up on Slack without reading it. Unreads, threads, search. Browser-session or hosted OAuth.32stars

prompts.chat MCP Serverf/prompts.chat-mcpSearch and retrieve AI prompts from prompts.chat, the social platform for AI prompts.28stars

Outlook Calendarmintmcp/serversA MCP server that works with Outlook Calendar to manage event listing, reading, and updates.0stars

Whatsapp Macoskalki-kgp/whatsapp-mcpWhatsApp MCP for macOS - Read messages from local DB, send via WhatsApp Web.2stars