chigwell/telegram-mcp

🤖 MCP in Action
Basic Telegram MCP usage in Claude:
Asking Claude to analyze chat history and send a response:
Message sent successfully:
Contents
- Skills & Practical Workflows
- What It Can Do
- Requirements
- Quick Start
- MCP Client Configuration
- Multi-Account Setup
- Device Identity
- Expected Account Check
- Proxy Support
- File Path Security
- Chat Access Privacy (Allowlist)
- Docker
- Development
- Security Notes
- Troubleshooting
- License
Skills & Workflows
Looking for ready-to-use workflows, prompt examples, or integration recipes?
Explore the **Skills Documentation** for step-by-step guides on:
- Summarizing unread messages safely
- Drafting replies without sending
- Triaging action items & urgent requests
- Searching chat history and expanding context
What It Can Do
The server currently includes 80+ MCP tools grouped into these areas:
- **Accounts:** list configured accounts and route tool calls by account label.
- **Chats and groups:** list chats, inspect metadata, create groups/channels, join or leave chats, invite or remove users, manage admins, bans, default permissions, slow mode, topics, invite links, common chats, read receipts, and message links.
- **Messages:** send, schedule, edit, delete, forward, pin, unpin, mark read, reply, search, inspect context, create polls, manage reactions, inspect inline buttons, and press inline callbacks. send_message, reply_to_message, and edit_message support classic formatting (parse_mode='md'/'html') and server-side rich formatting (parse_mode='rich'/'rich_markdown'/'rich_html' — full Markdown/HTML with tables, headings, formulas, and collapsible sections). Rich modes require Telegram Premium on the account; Premium is re-checked on every call, and without it nothing is sent — the tool returns a structured telegram_premium_required result so the agent can reformat with classic modes and retry. send_message, reply_to_message, and edit_message also accept format_date to render a date as a tappable chip.
get_message_reactions returns an empty list for a message with no reactions. To reuse a custom reaction, pass the returned custom: value to send_reaction.
vote_poll(chat_id, message_id, option_indices, account=None) votes in an existing poll.
Read the poll with get_messages first, then select zero-based answer indices: [0]
for the first answer, or [0, 2] for the first and third in a multiple-choice poll.
This may replace an existing vote; empty selections, duplicate or out-of-range
indices, closed polls, and multiple answers in single-choice polls are rejected.
Telegram enforces voting permissions and restrictions on changing quiz votes.
- **Contacts:** list, search, add, delete, block, unblock, import, export, inspect direct chats, find recent contact interactions, and remember contacts by the names you actually use (see below).
Remembered contacts
set_contact_alias teaches the server what you call someone, and every tool that takes a chat_id understands it from then on — send_message("андрей бекендер", ...) just works. A contact can carry any number of aliases, which is how tags work: save both андрей бекендер and бекендер for the same person and either resolves.
**Only an exact saved wording ever sends.** Similar wording (Андрею бекендеру for a saved андрей бекендер) is matched too, but only to *suggest*: the tool sends nothing and asks you to confirm the contact by name. This is deliberate — Лена/Леня and Иван/Иванов differ exactly as much as a case ending does, so a matcher confident enough to handle declensions is also confident enough to message the wrong person whenever the one you meant is not saved yet. Confirming saves that wording as its own alias, so each new phrasing costs one yes/no the first time and nothing ever again. Set TELEGRAM_CONTACT_FUZZY=0 to drop the suggestions too.
When a reference is unknown, resembles one contact, matches several, or points at a contact that no longer resolves, tools send nothing and return a structured instruction telling the agent exactly what to ask you, to save the answer with set_contact_alias, and to retry once. list_contact_aliases shows one row per person with all their aliases (use it to spot a wrong memory), delete_contact_alias forgets one, and repointing an alias at someone else requires replace=True. The save path itself refuses a target it would have to guess at: contacts are saved by @username, phone, numeric ID, or an alias already confirmed for them.
Aliases live in ${XDG_STATE_HOME:-~/.local/state}/telegram-mcp/aliases.json (owner-only, written atomically); TELEGRAM_ALIASES_FILE overrides the path, and a pre-existing aliases.json next to the code is still read as a fallback.