io.github.leshchenko1979/fast-mcp-telegram

Official8 tools

Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API

Send and receive Telegram messages through AI agents via HTTP and stdio protocols.

Captured live from the server via tools/list.

search_messages_globally

Search all Telegram chats at once (not scoped to one chat). Comma-separated query terms; optional filters by date, chat kind, and public username. Success: message list and metadata dict. Global search ignores include_total_count. Full documentation: https://github.com/leshchenko1979/fast-mcp-telegram/blob/main/docs/Tools-Reference.md

Parameters (8)

querystringrequired
Search terms, comma-separated for multiple terms (OR-style global search). Required.
limitinteger
Maximum messages to return (recommended 50 or less).
min_datestring
Inclusive minimum date filter (ISO 8601 date or datetime). Omit for no lower bound.
max_datestring
Inclusive maximum date filter (ISO 8601 date or datetime). Omit for no upper bound.
chat_typestring
Comma-separated chat kinds: private, bot, group, channel. Case-insensitive; extra spaces allowed.
publicboolean
If true, prefer chats with a public username; if false, without. Does not apply to private DMs. Omit to skip this filter.
auto_expand_batchesinteger
Extra search batches to run when filters narrow results. Higher values may return more matches at the cost of latency.
include_total_countboolean
If true, response may include total_count where supported (per-chat search; ignored for global search).

get_messages

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 each result. Use include_reply_threads to fetch up to 5 direct replies per result. Do not combine message_ids with query or reply_to_id. Success: messages, has_more, optional total_count and discussion fields. Full documentation: https://github.com/leshchenko1979/fast-mcp-telegram/blob/main/docs/Tools-Reference.md

Parameters (13)

chat_idstringrequired
Target chat: numeric id (e.g. -100…), username without @, or 'me' for Saved Messages.
querystring
Search within this chat only; comma-separated terms. Omit to browse latest or use message_ids / reply_to_id modes.
message_idsarray
Exact message ids to fetch. Mutually exclusive with query and reply_to_id.
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, not whole topic); supergroup threads use search top_msg_id. direct: immediate replies only.
limitinteger
Maximum messages to return (recommended 50 or less).
min_datestring
Inclusive minimum date filter (ISO 8601 date or datetime). Omit for no lower bound.
max_datestring
Inclusive maximum date filter (ISO 8601 date or datetime). Omit for no upper bound.
from_userstring
Only return messages from this sender. Accepts: numeric user id, @username, phone (+…), 'me', 'self', t.me URL, -100 prefixed id. Resolved via get_entity_by_id (same as chat_id). Uses Telegram's native from_id server-side filter (per-chat search only).
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 to and top replies (if include_reply_threads=true). Requires chat_id. Disabled when result count exceeds cost-based caps.
include_reply_threadsboolean
If true, fetch up to 5 direct replies per search result and attach as reply_thread. Each result costs one API call (not batchable). Default: false.
auto_expand_batchesinteger
Extra search batches to run when filters narrow results. Higher values may return more matches at the cost of latency.
include_total_countboolean
If true, response may include total_count where supported (per-chat search; ignored for global search).

send_message

Send text and optional file attachments to a Telegram chat. Supports reply-to (including forum topics and channel discussion groups), auto-detected or explicit parse_mode (markdown/html), and file attachments as http(s) URLs, local paths, or data: URIs. When files are provided, the message text becomes a caption. For channel posts with reply_to_id, automatically posts in the linked discussion group. Success: dict with message_id, date, chat, text, status='sent', and sender info. Error: dict with ok=false and error string. Use send_message to create new messages; use edit_message to modify existing ones. Use send_message_to_phone when targeting a phone number instead of a chat_id. Full documentation: https://github.com/leshchenko1979/fast-mcp-telegram/blob/main/docs/Tools-Reference.md

Parameters (5)

chat_idstringrequired
Target chat: numeric id (e.g. -100…), username without @, or 'me' for Saved Messages.
messagestringrequired
Message text. When sending files, used as caption.
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.
parse_modestring
'markdown', 'html', or 'auto' (detect from content). Default is 'auto'.
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.

edit_message

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. Success: dict with message_id, date, chat, text, status='edited', and edit_date. Error: dict with ok=false and error string (e.g. message not found or not editable). Use edit_message to update a previously sent message; use send_message to create new ones. Full documentation: https://github.com/leshchenko1979/fast-mcp-telegram/blob/main/docs/Tools-Reference.md

Parameters (4)

chat_idstringrequired
Target chat: numeric id (e.g. -100…), username without @, or 'me' for Saved Messages.
message_idintegerrequired
Message id in this chat to edit (from get_messages or Telegram).
messagestringrequired
Message text. When sending files, used as caption.
parse_modestring
'markdown', 'html', or 'auto' (detect from content). Default is 'auto'.

find_chats

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; include_peers filters use last-activity from GetPeerDialogs; flag-based filters use dialog list dates. Success: dict with key chats (list of chat objects). Full documentation: https://github.com/leshchenko1979/fast-mcp-telegram/blob/main/docs/Tools-Reference.md

Parameters (7)

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.
limitinteger
Maximum chats to return (recommended 50 or less).
chat_typestring
Comma-separated chat kinds: private, bot, group, channel. Case-insensitive; extra spaces allowed.
publicboolean
If true, prefer chats with a public username; if false, without. Does not apply to private DMs. Omit to skip this filter.
min_datestring
Inclusive minimum date filter (ISO 8601 date or datetime). Omit for no lower bound.
max_datestring
Inclusive maximum date filter (ISO 8601 date or datetime). Omit for no upper bound.
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 custom criteria (pinned, unread, business, etc.). See Filters-vs-Folders.md for the technical distinction.

get_chat_info

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

Parameters (2)

chat_idstringrequired
Target chat: numeric id (e.g. -100…), username without @, or 'me' for Saved Messages.
topics_limitinteger
Max forum topics to list when the chat is a forum.

send_message_to_phone

Send to a phone number: may create a temporary contact, then send text or files. Success: send result plus contact_was_new / contact_removed when applicable. Full documentation: https://github.com/leshchenko1979/fast-mcp-telegram/blob/main/docs/Tools-Reference.md

Parameters (8)

phone_numberstringrequired
E.164 phone number with country code, e.g. +1234567890 (must be on Telegram).
messagestringrequired
Message text. When sending files, used as caption.
first_namestring
First name when creating a temporary contact.
last_namestring
Last name when creating a temporary contact.
remove_if_newboolean
If true, delete the contact after send when it was created only for this send.
reply_to_msg_idinteger
Reply to this message id in the target chat after resolve.
parse_modestring
'markdown', 'html', or 'auto' (detect from content). Default is 'auto'.
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.

invoke_mtproto

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. Full documentation: https://github.com/leshchenko1979/fast-mcp-telegram/blob/main/docs/Tools-Reference.md

Parameters (4)

method_full_namestringrequired
Telegram API method, e.g. "messages.GetHistory" or "users.GetFullUser" (normalization applied).
params_jsonstringrequired
JSON object string of TL parameters as in Telegram API docs; nested TL uses "_": "typeName" discriminator.
allow_dangerousboolean
If false, destructive methods (e.g. deletes) are blocked. Set true only when intended.
resolveboolean
If true, resolve string/int peer-like fields to TL Input* entities before invoke.

Install

Configuration

Environment variables

API_IDrequired

Telegram API ID from my.telegram.org

API_HASHrequiredsecret

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/)

claude_desktop_config.json

{
  "mcpServers": {
    "fast-mcp-telegram": {
      "command": "uvx",
      "args": [
        "fast-mcp-telegram"
      ],
      "env": {
        "API_ID": "<YOUR_API_ID>",
        "API_HASH": "<YOUR_API_HASH>",
        "SERVER_MODE": "stdio",
        "SESSION_DIR": "<YOUR_SESSION_DIR>"
      }
    }
  }
}