# fast-mcp-telegram

An MCP gateway that lets your coding agent read and send Telegram messages: 8 tools, QR sign-in, and raw MTProto over HTTP.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 49
- Author: leshchenko1979
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/leshchenko1979/fast-mcp-telegram
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/mcp/fast-mcp-telegram

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Remote server: `https://tg-mcp.l1979.ru/v1/mcp`
- Environment variables: `API_ID`, `API_HASH`, `SERVER_MODE`, `SESSION_DIR` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

1. **Platform CLI: remote server**
```bash
claude mcp add --transport http fast-mcp-telegram https://tg-mcp.l1979.ru/v1/mcp
```

2. **Platform CLI**
```bash
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
```
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>

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add fast-mcp-telegram --url https://tg-mcp.l1979.ru/v1/mcp
```

2. **Platform CLI**
```bash
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-telegram
```
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>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "fast-mcp-telegram": {
            "url": "https://tg-mcp.l1979.ru/v1/mcp"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "fast-mcp-telegram": {
            "type": "http",
            "url": "https://tg-mcp.l1979.ru/v1/mcp"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http fast-mcp-telegram https://tg-mcp.l1979.ru/v1/mcp
```

2. **Platform CLI**
```bash
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-telegram
```
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>

## When to use it
- 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
- 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

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md