telegram-mcp — Claude Code MCP server for your Telegram
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.
claude mcp add telegram-mcp -- uvx telegram-mcp-jgaleaWhat telegram-mcp 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.
What it helps with
- 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 for the agent
- 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
How to install telegram-mcp
Platform CLI
claude mcp add telegram-mcp -- uvx telegram-mcp-jgaleauvx runs the command named after the package; if the README names another one, use uvx --from telegram-mcp-jgalea <command>
Platform CLI
codex mcp add telegram-mcp -- uvx telegram-mcp-jgaleauvx runs the command named after the package; if the README names another one, use uvx --from telegram-mcp-jgalea <command>
Config file
{
"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>
Config file
{
"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>
Platform CLI
gemini mcp add telegram-mcp uvx telegram-mcp-jgaleauvx runs the command named after the package; if the README names another one, use uvx --from telegram-mcp-jgalea <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 telegram-mcp
How do I install telegram-mcp in Claude Code?
Run claude mcp add telegram-mcp -- uvx telegram-mcp-jgalea, then run telegram-mcp login once in a terminal and finish the phone login.
What does telegram-mcp do?
It gives an agent access to your Telegram account: reading and searching messages, sending and editing them, plus groups, channels, contacts and media.
Why do the tools return errors?
Usually because login was never completed — installing the server and signing in are separate steps. Run telegram-mcp login in a real terminal, then restart your MCP client.
