Telegram MCP Server

A Model Context Protocol (MCP) server that connects Claude Code to your Telegram user account via the MTProto API (Telethon). It lets Claude search channels, read messages, list your chats, and send messages — all from inside a Claude Code session.

---

Features

Tool	Description
tg_auth_status	Check whether the current session is logged in
tg_search_channels	Search Telegram's global directory for public channels/groups by keyword
tg_search_messages_global	Search messages globally across all public Telegram channels
tg_search_messages_in_channel	Search messages inside a specific channel by @username or ID
tg_get_channel_info	Get title, member count, and description of a public channel
tg_get_recent_messages	Fetch recent messages from any channel (joined or public)
tg_list_dialogs	List your joined chats, groups, and channels with unread counts
tg_send_message	Send a text message to any chat or channel you're a member of

---

Requirements

• Python 3.10+
• A Telegram account
• A Telegram API app (free — takes 1 minute to create)

Python dependencies

pip install telethon mcp

---

Setup

1. Get Telegram API credentials

1. Go to https://my.telegram.org/apps and log in
2. Click Create application
3. Fill in any app name and short name (e.g. myapp)
4. Copy your api_id (a number) and api_hash (a string)

2. Clone the repo

git clone https://github.com/blackaleader/telegram-mcp.git
cd telegram-mcp

3. Log in to your Telegram account

Run the login script once interactively. It will save a session file to data/session.session so you never need to log in again.

TELEGRAM_API_ID=your_api_id TELEGRAM_API_HASH=your_api_hash TELEGRAM_PHONE=+1234567890 python login.py

Or just run python login.py and it will prompt you for each value.

You'll receive a code on Telegram — enter it when prompted. If you have 2FA enabled, you'll be asked for your password too.

4. Configure Claude Code

Add the MCP server to your Claude Code config. The global config file is at ~/.claude/.mcp.json:

{
  "mcpServers": {
    "telegram-user": {
      "command": "python",
      "args": ["/absolute/path/to/telegram-mcp/server.py"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash"
      }
    }
  }
}

Windows users: use py instead of python and use double backslashes or forward slashes in the path.

5. Restart Claude Code

After saving .mcp.json, restart Claude Code. The tools will appear automatically.

---

Tool Reference

tg_auth_status

Check if the saved session is still authorized.

{}

Returns: { "logged_in": true, "name": "...", "username": "...", "phone": "..." }

---

tg_search_channels

Search Telegram's public channel directory by keyword. Works for channels you haven't joined.

{
  "query": "سریال ایرانی",
  "limit": 20
}

Returns: Array of { id, type, title, username, members, verified }

---

tg_search_messages_global

Search messages globally across public Telegram channels (equivalent to Telegram's Explore search bar).

{
  "query": "breaking news",
  "limit": 20,
  "broadcasts_only": true
}

• broadcasts_only: when true, limits results to broadcast channels (not groups)

Returns: Array of { id, date, chat, text, views }

---

tg_search_messages_in_channel

Search messages inside a specific channel. Works even if you haven't joined it.

{
  "channel": "@bbcpersian",
  "query": "keyword",
  "limit": 20
}

Returns: Array of { id, date, chat, text, views }

---

tg_get_channel_info

Get full info about a public channel.

{
  "channel": "@durov"
}

Returns: { id, type, title, username, members, verified, description }

---

tg_get_recent_messages

Fetch the latest messages from a channel or group.

{
  "channel": "@telegram",
  "limit": 20
}

Returns: Array of { id, date, chat, text, views }

---

tg_list_dialogs

List all your joined chats, groups, and channels with unread counts.

{
  "limit": 30
}

Returns: Array of { id, name, unread, type, username }

---

tg_send_message

Send a message to a chat, group, or channel (you must be a member).

{
  "chat": "@username",
  "text": "Hello!"
}

Returns: { "sent": true, "message_id": 12345 }

---

Project Structure

telegram-mcp/
├── server.py        # MCP server — all 8 tools defined here
├── login.py         # One-time interactive login script
├── data/
│   └── session.session   # Saved Telegram session (git-ignored)
└── .mcp.json        # Example Claude Code MCP config

---

Security Notes

• Never commit data/session.session — it gives full access to your Telegram account. It is listed in .gitignore.
• Never commit your api_id / api_hash — pass them via environment variables only.
• This server uses your user account (MTProto), not a bot token. It can read and send messages on your behalf.

---

Troubleshooting

Tools don't appear in Claude Code

• Make sure .mcp.json is valid JSON and the path to server.py is absolute
• Restart Claude Code after editing .mcp.json
• Run python server.py manually to check for import errors

NOT LOGGED IN error

• Re-run python login.py — your session may have expired
• Make sure data/session.session exists and is not empty

FloodWaitError

• Telegram rate-limited the request. Wait the indicated number of seconds and retry.

---

License

MIT