# telegram-mcp

Wires your own Telegram account into an AI agent so it can read chats, search history, send replies and pull down media without you opening the app.

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

## What it does

This server speaks MTProto through Telethon rather than the Bot API. Everything you see in the Telegram app is reachable: private conversations, groups, channels, media. Around forty tools cover listing dialogs, reading and searching messages by keyword or regex, sending, editing, forwarding, scheduling, reactions, contacts and group management.

As you use it, messages land in a local SQLite cache. There is no sync command to run — the searchable history just grows. The session file lives at `~/.telegram-mcp/session.session` with restricted permissions, credentials stay out of config files, and rate limiting is built in.

You need an `api_id` and `api_hash` from my.telegram.org before anything works. Login is interactive: Telegram texts a code to your phone and you type it at a terminal prompt. An agent can write the MCP config and clone the repo, but it cannot get past that step. Skip it and the tools come back empty or error out — and the agent may then claim the server only reaches a bot conversation. That claim is wrong; the missing login is the real cause.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add telegram-mcp -- uvx telegram-mcp-jgalea
```
uvx runs the command named after the package; if the README names another one, use uvx --from telegram-mcp-jgalea <command>

### Codex

**Platform CLI**
```bash
codex mcp add telegram-mcp -- uvx telegram-mcp-jgalea
```
uvx runs the command named after the package; if the README names another one, use uvx --from telegram-mcp-jgalea <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "telegram-mcp": {
            "command": "uvx",
            "args": [
                "telegram-mcp-jgalea"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from telegram-mcp-jgalea <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "telegram-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "telegram-mcp-jgalea"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from telegram-mcp-jgalea <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add telegram-mcp uvx telegram-mcp-jgalea
```
uvx runs the command named after the package; if the README names another one, use uvx --from telegram-mcp-jgalea <command>

## When to use it
- catch up on unread messages in work groups
- dig up a link someone posted last week
- reply to a DM without switching apps
- download a file or photo sent in a chat
- spin up a group and pin a message in it

## Example prompts
- Show me unread messages from today
- Search my chat with Anna for anything about the contract
- Send “call moved an hour later” to the Team group

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

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