Content
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.linkedin.com/in/eugene-evstafev-716669181/)
# Telegram MCP Server
A Telegram MCP (Model Context Protocol) server built using Python, Telethon, and MCP Python SDK. This MCP server provides simple tools for interacting with Telegram chats directly through MCP-compatible hosts, such as Claude for Desktop.
## Tools Provided
- **`get_chats`**: Retrieve a paginated list of your Telegram chats.
- **`get_messages`**: Retrieve paginated messages from a specific chat.
- **`send_message`**: Send a message to a specific chat.
## Requirements
- Python 3.10 or higher
- [Telethon](https://docs.telethon.dev/) package
- [MCP Python SDK](https://modelcontextprotocol.io/docs/)
- [UV](https://astral.sh/uv/) (optional but recommended)
## Installation and Setup
### Clone the Repository
```bash
git clone https://github.com/chigwell/telegram-mcp
cd telegram-mcp
```
### Create Environment File
Copy and rename `.env.example` to `.env` and fill it with your Telegram credentials obtained from [https://my.telegram.org/apps](https://my.telegram.org/apps):
```bash
cp .env.example .env
```
Your `.env` file should look like:
```env
TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_SESSION_NAME=your_session_name
```
### Setup Python Environment
Use `uv` to set up the Python environment and install dependencies:
```bash
uv venv
source .venv/bin/activate
uv add "mcp[cli]" telethon python-dotenv nest_asyncio
```
### Run the Server (First-time Auth)
The first time you run the server, Telethon will prompt you to enter a Telegram authentication code:
```bash
uv run main.py
```
Authenticate by entering the code sent to your Telegram client. This step is only required once.
## Integrating with Claude for Desktop
### macOS/Linux
Edit your Claude Desktop configuration:
```bash
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
Add this MCP server configuration:
```json
{
"mcpServers": {
"telegram-mcp": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE_PATH/telegram-mcp",
"run",
"main.py"
]
}
}
}
```
Ensure you replace `/ABSOLUTE_PATH/telegram-mcp` with your project's absolute path.
### Windows
Edit your Claude Desktop configuration:
```powershell
nano $env:AppData\Claude\claude_desktop_config.json
```
Add this MCP server configuration:
```json
{
"mcpServers": {
"telegram-mcp": {
"command": "uv",
"args": [
"--directory",
"C:\\ABSOLUTE_PATH\\telegram-mcp",
"run",
"main.py"
]
}
}
}
```
Ensure you replace `C:\ABSOLUTE_PATH\telegram-mcp` with your project's absolute path.
## Usage
Once integrated, your Telegram tools (`get_chats`, `get_messages`, and `send_message`) will become available within the Claude for Desktop UI or any other MCP-compatible client.
## License
This project is licensed under the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0).
