fast-mcp-telegram — Claude Code MCP server for Telegram
An MCP gateway that lets your coding agent read and send Telegram messages: 8 tools, QR sign-in, and raw MTProto over HTTP.
claude mcp add --transport http fast-mcp-telegram https://tg-mcp.l1979.ru/v1/mcpWhat fast-mcp-telegram does
The server sits in the middle: your agent talks MCP or HTTP, the server talks MTProto to Telegram. Instead of exposing dozens of micro-methods it ships 8 tools — search across chats and messages, read by ID, send and edit, attach files, pull replies from channel posts and forum topics. One deployment can host several people, each with their own Bearer token and Telegram session.
Sign-in happens on the /setup page. Scan the QR code from Telegram mobile (Settings → Devices → Scan QR) and copy the token you get; phone number with code and 2FA works as a fallback. From there you either download mcp.json for your client or call the API directly with curl, for instance messages.SendMessage.
A local run needs API_ID and API_HASH from Telegram plus a SESSION_DIR for session files. If one agent holds several connections to the same server under different tokens, turn on PREFIX_MCP_TOOLS_WITH_ACCOUNT — without it tool names collide. On a shared host, ACL_ENABLED adds per-principal limits: chat lanes, read_only, blocked peers.
What it helps with
- find a message across chat history with several queries at once
- send a file or photo to a chat from the agent
- read replies under a channel post or forum topic
- give several users separate access to one server via tokens
- call an arbitrary Telegram API method with curl
Example prompts for the agent
- Send hello to my saved messages in telegram
- Search my chats for the contract and show the surrounding context
- Read the replies under the latest channel post
How to install fast-mcp-telegram
1Platform CLI: remote server
claude mcp add --transport http fast-mcp-telegram https://tg-mcp.l1979.ru/v1/mcp2Platform CLI
claude mcp add --env API_ID=<API_ID> --env API_HASH=<API_HASH> --env SERVER_MODE=<SERVER_MODE> --env SESSION_DIR=<SESSION_DIR> --transport stdio fast-mcp-telegram -- uvx fast-mcp-telegramReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from fast-mcp-telegram <command>
1Platform CLI: remote server
codex mcp add fast-mcp-telegram --url https://tg-mcp.l1979.ru/v1/mcp2Platform CLI
codex mcp add fast-mcp-telegram --env API_ID=<API_ID> --env API_HASH=<API_HASH> --env SERVER_MODE=<SERVER_MODE> --env SESSION_DIR=<SESSION_DIR> -- uvx fast-mcp-telegramReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from fast-mcp-telegram <command>
Config file
{
"mcpServers": {
"fast-mcp-telegram": {
"url": "https://tg-mcp.l1979.ru/v1/mcp"
}
}
}{
"mcpServers": {
"fast-mcp-telegram": {
"command": "uvx",
"args": [
"fast-mcp-telegram"
],
"env": {
"API_ID": "<API_ID>",
"API_HASH": "<API_HASH>",
"SERVER_MODE": "<SERVER_MODE>",
"SESSION_DIR": "<SESSION_DIR>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from fast-mcp-telegram <command>
Config file
{
"servers": {
"fast-mcp-telegram": {
"type": "http",
"url": "https://tg-mcp.l1979.ru/v1/mcp"
}
}
}{
"servers": {
"fast-mcp-telegram": {
"type": "stdio",
"command": "uvx",
"args": [
"fast-mcp-telegram"
],
"env": {
"API_ID": "<API_ID>",
"API_HASH": "<API_HASH>",
"SERVER_MODE": "<SERVER_MODE>",
"SESSION_DIR": "<SESSION_DIR>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from fast-mcp-telegram <command>
1Platform CLI: remote server
gemini mcp add -t http fast-mcp-telegram https://tg-mcp.l1979.ru/v1/mcp2Platform CLI
gemini mcp add -e API_ID=<API_ID> -e API_HASH=<API_HASH> -e SERVER_MODE=<SERVER_MODE> -e SESSION_DIR=<SESSION_DIR> fast-mcp-telegram uvx fast-mcp-telegramReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from fast-mcp-telegram <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about fast-mcp-telegram
How do I install fast-mcp-telegram in Claude Code?
For the remote server: claude mcp add --transport http fast-mcp-telegram https://tg-mcp.l1979.ru/v1/mcp. For a local one: `claude mcp add --env API_ID=<API_ID> --env API_HASH=<API_HASH> --env SERVER_MODE=<SERVER_MODE> --env SESSION_DIR=<SESSION_DIR> --transport stdio fast-mcp-telegram -- uvx fast-mcp-telegram`.
What does fast-mcp-telegram do?
It bridges an AI agent to Telegram over MTProto and exposes 8 tools for searching, reading, sending messages and handling files. A single server can serve multiple users with isolated sessions.
What do I need for a local run?
API_ID and API_HASH from Telegram, and a SESSION_DIR where session files live. The server starts with uvx fast-mcp-telegram.
