Telegram MCP server

telegram-mcp

<!-- mcp-name: io.github.jgalea/telegram-mcp -->

Give your AI tools direct access to Telegram. Read chats, send messages, search history, manage groups, download media — all via the Model Context Protocol.

telegram-mcp is an MCP server that connects your Telegram account to Claude Code, Cursor, Windsurf, or any AI tool that supports MCP. Instead of switching to Telegram, you ask the AI to check your messages, reply to someone, or find that link from last week — and it does.

What makes this different:

• Your real account. Uses MTProto (Telethon), not the Bot API. You see everything you'd see in the Telegram app — private chats, groups, channels, media.
• 40 tools. Chats, messages, search, media, contacts, groups, channels, scheduling, reactions, admin tools, and more.
• Passive caching. Messages are cached in local SQLite as you use the server. No explicit sync step — the cache builds itself. Gives you searchable history that grows over time.
• Security first. Session files stored with restricted permissions. No credentials in config files. Rate limiting built in.

Quick Start

This is not a bot. There is no bot to add. No third party gives you a phone number. You log in as yourself, with the same phone number you already use for Telegram. If an AI tool tells you to "add a bot to give you a number", ignore it — and never share a Telegram login code with anyone, ever.

If you're asking Claude (or another AI agent) to install this for you: the agent can wire up the MCP server config and clone the repo, but the agent cannot complete the login step. Login is interactive — Telegram sends a code to your phone, and you type it into a terminal prompt yourself. You must run telegram-mcp login in a real terminal once, then the agent can use the server.

Install from PyPI

uv tool install telegram-mcp-jgalea

Or with pip:

pip install telegram-mcp-jgalea

Both provide the telegram-mcp command.

Install from source

git clone https://github.com/jgalea/telegram-mcp.git
cd telegram-mcp
uv sync

Authenticate

Run the login command once to create your Telegram session:

telegram-mcp login

You'll need a Telegram API ID and hash first. To get them:

1. Go to my.telegram.org and log in with your phone number
2. Click API development tools
3. If you already have an app, use those credentials. Telegram only allows one API app per account, and the same apiid/apihash work for any Telegram project.
4. If not, fill in the form: App title (e.g. "telegram-mcp"), Short name (anything), Platform: "Other". Description can be left blank. Click Create application.
5. Copy the App apiid (a number) and App apihash (a hex string)

The login command will prompt for these if not already configured, then ask for:

1. Your phone number
2. The verification code Telegram sends you
3. Your 2FA password (if enabled)

The session is saved to ~/.telegram-mcp/session.session. You only need to do this once.

Connect to Claude Code

Add to your MCP config (~/.claude.json):

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-mcp",
      "args": ["serve"]
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/telegram-mcp", "telegram-mcp", "serve"]
    }
  }
}

Troubleshooting

Tools return errors or empty results

You almost certainly haven't logged in yet. Installing the MCP server and logging into Telegram are two separate steps — installation alone is not enough. Run telegram-mcp login in a real terminal and complete the phone + code + 2FA flow. After that, restart Claude Code (or your MCP client) so the proxy picks up the new session.

Shortened. The full README is on GitHub.