# Fast MCP Telegram

> Fast MCP Telegram is an open-source MCP server for communication. Multi-tenant Telegram gateway giving agents eight tools over a user account via MTProto. It can run locally on your machine or as a hosted remote server.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** telegram, self-hosted, CLI, API
- **Repository:** https://github.com/leshchenko1979/fast-mcp-telegram
- **MCP Registry name:** io.github.leshchenko1979/fast-mcp-telegram
- **Categories:** communication
- **Listing updated:** 2026-11-14

## About

This server acts as a bridge between an agent and Telegram's user API (MTProto) rather than the bot API. The README says it consolidates what could be 80 or more micro-tools into eight, to keep context small, and annotates them with MCP tool annotations.

It runs in two modes: stdio for a local client, or an HTTP server with Bearer tokens where each user gets an isolated session. Setup can use a QR scan from Telegram mobile, a phone number with code and 2FA, or a bot token. A hosted demo has a web setup page, and an optional ACL can restrict a principal to read-only access, blocked peers or limited chat lanes.

A separate HTTP bridge lets curl call any Telegram API method with entity resolution and guardrails. Messaging covers send, edit, reply, forum topics, formatting and file attachments with SSRF protection, and Premium accounts get voice transcription. Sessions can be kept in S3-compatible storage.

## Features

- **Eight consolidated tools:** Fewer tools to keep an agent's context small.
- **Unified message reading:** One get_messages tool searches, browses, reads by ID and fetches replies.
- **QR login:** Authenticate by scanning a code from Telegram mobile, with no OTP or 2FA.
- **Multi-user hosting:** One Bearer token per user, each with its own Telegram session.
- **Session ACL:** Optional per-user limits such as read-only, blocked peers and chat lanes.
- **MTProto HTTP bridge:** Call any Telegram API method with curl, with safety guardrails.
- **File and media sending:** Upload files, base64 inline files and albums with SSRF protection.
- **Voice transcription:** Speech-to-text for Premium accounts.

## Good for

- Let an assistant search chat history across Telegram
- Draft and send replies, including in forum topics
- Post messages with attachments to a channel
- Host one Telegram gateway for several users
- Run raw Telegram API calls from scripts

## Install

### Claude Code (Terminal)

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

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://tg-mcp.l1979.ru/v1/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "fast-mcp-telegram": {
      "url": "https://tg-mcp.l1979.ru/v1/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "fast-mcp-telegram": {
      "type": "http",
      "url": "https://tg-mcp.l1979.ru/v1/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "fast-mcp-telegram": {
      "serverUrl": "https://tg-mcp.l1979.ru/v1/mcp"
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "fast-mcp-telegram": {
      "type": "http",
      "url": "https://tg-mcp.l1979.ru/v1/mcp"
    }
  }
}
```

## Tools

- `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. Results are ordered by ascending date-time (oldest first); limit selects the newest N. Success: message list and metadata dict. Global search ignores include_total_count. Full documentation: https://github.com/leshchenko1979/fast-mcp-telegram/blob/main/
- `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_replies to fetch up to 5 direct replies per result. Do not combine message_ids with query or reply_t
- `send_message`: 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 with files. File attachments as http(s) URLs, local paths, or data: URIs. When files are provided, the message text becomes a
- `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. parse_mode: classic markdown/html/auto or rich (Rich Message; dialect auto-detected). schedule_date (ISO 8601) reschedules an already-queued message; it does not turn a delivered message into a scheduled one, and the result
- `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 ke
- `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; user targets may include common_chats up to common_chats_limit. Full documentation: https://github.com/leshchenko1979/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
- `send_message_to_phone`: 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 instead of delivering now; save_as_draft=true saves the text as the draft in that chat instead of sending. Success: send resu
- `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. PII and credential-shaped fields (phone, access_hash) are dropped from a successful result by default; pass include_sensitive=true for the raw payload. A bare message id needs a chat binding: requests with no peer field (messa

## FAQ

### Do I need Telegram API credentials?

For local use, yes: an API ID and hash from my.telegram.org. The hosted demo instead uses a QR scan to give you a token.

### What licence does it use?

The README badge shows MIT.

### Can I restrict what an agent does?

Yes. The optional session ACL supports read-only mode, blocked peers and denying unlisted principals.

### How does it run?

As a stdio server via uvx, or as an HTTP server with auth.

### Is Fast MCP Telegram free?

Yes. Fast MCP Telegram is open source, so you can use and self-host it for free.

### How do I add Fast MCP Telegram to Claude Code?

Run this command in your terminal: claude mcp add --transport http fast-mcp-telegram https://tg-mcp.l1979.ru/v1/mcp

### What are the best alternatives to Fast MCP Telegram?

The closest alternatives to Fast MCP Telegram are BoardAgent, Callout, nicemails, SOMMON Office and PostBaton.

## Alternatives

- [BoardAgent](https://ai-powered.com/mcp/boardagent): BoardAgent is a free MCP server for community directories.
- [Callout](https://ai-powered.com/mcp/callout): Callout is a freemium MCP server for communication.
- [nicemails](https://ai-powered.com/mcp/nicemails): nicemails is a freemium MCP server for communication.
- [SOMMON Office](https://ai-powered.com/mcp/sommon-office): SOMMON Office is a paid MCP server for communication.
- [PostBaton](https://ai-powered.com/mcp/postbaton): PostBaton is a freemium MCP server for marketing and seo.
- [MeetBetr](https://ai-powered.com/mcp/meetbetr): MeetBetr is a free MCP server for productivity.
- [Host Tools](https://ai-powered.com/mcp/host-tools): Host Tools is an MCP server for home services.
- [iMessage MCP](https://ai-powered.com/mcp/imessage-mcp): iMessage MCP is an open-source MCP server for communication.

---
Source: https://ai-powered.com/mcp/fast-mcp-telegram
