Telegram MCP Server
Connect Claude to your Telegram account to read and send messages.
Features
Available Tools
-
get_chats - List your Telegram chats
- Returns paginated list with chat names, IDs, and unread counts
- For page 1, just provide page number
- For subsequent pages, use the pagination parameters from the previous response
-
get_messages - Read messages from a specific chat
- Fetches paginated message history
- Automatically marks messages as read
-
mark_messages_read - Mark all unread messages in a chat as read
-
send_message - Send messages to any chat
- Supports replying to specific messages
-
get_conversation_context - Analyze chat style for natural responses
- Reads your conversation style guide from
convostyle.txt - Helps Claude match your texting patterns
- Reads your conversation style guide from
Setup Guide
Step 1: Get Telegram API Credentials
- Go to https://my.telegram.org/apps
- Log in and create an application
- Save your API ID and API Hash
Step 2: Install
# Clone the repository
git clone https://github.com/alexandertsai/mcp-telegram
cd mcp-telegram
# Set up Python environment
pip install uv
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv sync
Step 3: Configure
# Copy the example file
cp .env.example .env
# Edit .env and add your API credentials:
# TELEGRAM_API_ID=your_api_id_here
# TELEGRAM_API_HASH=your_api_hash_here
Step 4: Authenticate
cd src/mcp_telegram
python telethon_auth.py
Follow the prompts:
- Enter your phone number (with country code, e.g., +1234567890)
- Enter the code sent to your Telegram
- Enter your 2FA password if you have one
Step 5: Add to Claude Desktop
Find your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Add this configuration:
{
"mcpServers": {
"telegram": {
"command": "/path/to/python",
"args": ["/path/to/mcp-telegram/src/mcp_telegram/main.py"]
}
}
}
To find paths:
- Python: Run
which python(Mac) orwhere.exe python(Windows) - main.py: Right-click the file and select "Copy Path"
Restart Claude Desktop.
Usage
After setup, you can ask Claude to:
- "Check my Telegram messages"
- "Send a message to [contact name]"
- "What are my unread chats?"
- "Reply to the last message from [contact name]"
Style Guide (Optional)
Create src/mcp_telegram/convostyle.txt to help Claude match your texting style:
I text casually with friends, formally with work contacts.
I use emojis sparingly and prefer short messages.
Troubleshooting
Authentication Issues
If authentication fails:
- Check your API credentials in
.env - Remove the TELEGRAM_SESSION_STRING line from
.env - Run
python telethon_auth.pyagain
Common Errors
- "Please set TELEGRAM_API_ID and TELEGRAM_API_HASH": Missing
.envfile or credentials - "Session string is invalid or expired": Re-run authentication
- 2FA password not showing: This is normal - keep typing
Requirements
- Python 3.10+
- Claude Desktop
- Telegram account
License
Apache 2.0
Metadata
Release files for iflow-mcp_telegram-mcp 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_telegram_mcp-0.1.1.tar.gz | 12.1 kB | Without provenance | Details for iflow_mcp_telegram_mcp-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_telegram_mcp-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_telegram_mcp-0.1.1-py3-none-any.whl |
Total release size: 25.6 kB
Release files / iflow_mcp_telegram_mcp-0.1.1.tar.gz
| Download URL | iflow_mcp_telegram_mcp-0.1.1.tar.gz |
|---|---|
| Size | 12.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0af187f93b066a73ad21b92f3e8508c75ed66dd0252354a2975870b04d111339
|
|
BLAKE2b-256 checksum How to use checksums |
0c997a1e52b2bcab40bb04e864b438de8445c612c0e91654b0d74435c54244e8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.10 {"installer":{"name":"uv","version":"0.9.10"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_telegram_mcp-0.1.1-py3-none-any.whl
| Download URL | iflow_mcp_telegram_mcp-0.1.1-py3-none-any.whl |
|---|---|
| Size | 13.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
146ade6fcec26b1162a2b4f4f53a7adc2280b16c1f17bdd6192a0b411aa8fd68
|
|
BLAKE2b-256 checksum How to use checksums |
c2f9fff60ecd9c3dd188db6a021185051e300633fafd33c4a62e97c42c5502e0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.10 {"installer":{"name":"uv","version":"0.9.10"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_telegram-mcp 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.