# Chatroost — unofficial Telegram MCP server

Connect an AI assistant to Telegram to search chats, read messages, reply, and react. It works through your personal account rather than a bot account.

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

## What it does

Chatroost connects an assistant to Telegram over MTProto. It can search across chats, read conversations, send replies, and add reactions; tools for forum topics and contacts are included too. The server acts as a userbot, so actions use your own Telegram account.

A local setup needs Node.js 18 or later, plus `TELEGRAM_API_ID` and `TELEGRAM_API_HASH` from `my.telegram.org`. Sign in by scanning a QR code in Telegram, then the session is saved for later runs. Accounts with two-step verification also need the Telegram password during login.

In Claude Code, you can add the hosted HTTP server with the command below. A local connection gives the assistant access to chats under your personal account, so consider that before connecting it.

## Requirements
- Needs: Node.js (commands run via npx)
- Remote server: `https://mcp.mcp-telegram.com/mcp`
- Environment variables: `TELEGRAM_API_ID`, `TELEGRAM_API_HASH` — 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 mcp-telegram https://mcp.mcp-telegram.com/mcp
```

2. **Platform CLI**
```bash
claude mcp add --env TELEGRAM_API_ID=<TELEGRAM_API_ID> --env TELEGRAM_API_HASH=<TELEGRAM_API_HASH> --transport stdio chatroost-unofficial-telegram-mcp-server -- npx -y @overpod/mcp-telegram
```
Replace <…> with your own values

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add chatroost-unofficial-telegram-mcp-server --url https://mcp.mcp-telegram.com/mcp
```

2. **Platform CLI**
```bash
codex mcp add chatroost-unofficial-telegram-mcp-server --env TELEGRAM_API_ID=<TELEGRAM_API_ID> --env TELEGRAM_API_HASH=<TELEGRAM_API_HASH> -- npx -y @overpod/mcp-telegram
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "chatroost-unofficial-telegram-mcp-server": {
            "url": "https://mcp.mcp-telegram.com/mcp"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "chatroost-unofficial-telegram-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "@overpod/mcp-telegram"
            ],
            "env": {
                "TELEGRAM_API_ID": "<TELEGRAM_API_ID>",
                "TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "chatroost-unofficial-telegram-mcp-server": {
            "type": "http",
            "url": "https://mcp.mcp-telegram.com/mcp"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "chatroost-unofficial-telegram-mcp-server": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@overpod/mcp-telegram"
            ],
            "env": {
                "TELEGRAM_API_ID": "<TELEGRAM_API_ID>",
                "TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http chatroost-unofficial-telegram-mcp-server https://mcp.mcp-telegram.com/mcp
```

2. **Platform CLI**
```bash
gemini mcp add -e TELEGRAM_API_ID=<TELEGRAM_API_ID> -e TELEGRAM_API_HASH=<TELEGRAM_API_HASH> chatroost-unofficial-telegram-mcp-server npx -y @overpod/mcp-telegram
```
Replace <…> with your own values

## When to use it
- search messages across Telegram chats
- read a conversation and draft a reply
- send a message from your personal account
- react to a Telegram message
- read messages in a forum topic

## Example prompts
- Find Telegram messages about the release and summarize them.
- Read the latest message in the team chat and draft a reply.
- React to the newest message in this conversation.

## Similar
- [Notify MCP Server](https://affpapa.org/en/nevibecode/mcp/notify-mcp-server.md) — MCP server · ★ 28
- [TONNode — TON blockchain access](https://affpapa.org/en/nevibecode/mcp/tonnode-ton-blockchain-access.md) — MCP server · ★ 27
- [telegram-mcp](https://affpapa.org/en/nevibecode/mcp/telegram-mcp.md) — MCP server · ★ 7

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