# telegram-mcp
A **minimal** MCP server for Telegram bot interaction via MTProto — intentionally simple, easy to read, and easy to extend.
> **Looking for a full-featured Telegram MCP server?** Check out [chigwell/telegram-mcp](https://github.com/chigwell/telegram-mcp) — 60+ tools covering messaging, groups, contacts, media, admin, and more.
This project takes a different approach: **two tools, ~150 lines of server code, zero complexity.** It's a clean starting point for anyone who wants to understand how MCP servers work with Telegram, or who only needs basic bot messaging without the overhead of a full client.
## Why this exists
- **Learning reference** — Read the entire server in 5 minutes
- **Fork-friendly** — Add exactly the tools you need, nothing you don't
- **Minimal dependencies** — Just Telethon, MCP SDK, and python-dotenv
## Tools
| Tool | Description |
|------|-------------|
| `send_message` | Send a message to a Telegram bot and wait for its reply |
| `get_history` | Get message history with a Telegram bot |
## Setup
### 1. Get Telegram API credentials
1. Go to [https://my.telegram.org/apps](https://my.telegram.org/apps)
2. Log in with your phone number
3. Create a new application (any name/description)
4. Copy the **API ID** and **API Hash**
### 2. Install and authenticate
```bash
# Install
pip install git+https://github.com/tensakulabs/telegram-mcp.git
# Set your credentials
export TELEGRAM_API_ID=12345678
export TELEGRAM_API_HASH=abcdef1234567890abcdef1234567890
export TELEGRAM_PHONE=+15551234567
# Run one-time authentication (sends a code to your Telegram app)
telegram-mcp-auth
```
### 3. Configure your MCP client
#### Claude Code
Add to `~/.claude/settings.json`:
```json
{
"mcpServers": {
"telegram": {
"command": "uvx",
"args": ["--from", "git+https://github.com/tensakulabs/telegram-mcp.git", "telegram-mcp"],
"env": {
"TELEGRAM_API_ID": "your-api-id",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION_DIR": "/path/to/session/dir"
}
}
}
}
```
#### Claude Desktop
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"telegram": {
"command": "uvx",
"args": ["--from", "git+https://github.com/tensakulabs/telegram-mcp.git", "telegram-mcp"],
"env": {
"TELEGRAM_API_ID": "your-api-id",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION_DIR": "/path/to/session/dir"
}
}
}
}
```
#### Local development
If you've cloned the repo:
```json
{
"mcpServers": {
"telegram": {
"command": "uv",
"args": ["--directory", "/path/to/telegram-mcp", "run", "telegram-mcp"],
"env": {
"TELEGRAM_API_ID": "your-api-id",
"TELEGRAM_API_HASH": "your-api-hash"
}
}
}
}
```
## Configuration
| Environment variable | Required | Default | Description |
|---------------------|----------|---------|-------------|
| `TELEGRAM_API_ID` | Yes | — | Your Telegram API ID |
| `TELEGRAM_API_HASH` | Yes | — | Your Telegram API hash |
| `TELEGRAM_PHONE` | Auth only | — | Phone number for authentication |
| `TELEGRAM_ENV_PATH` | No | Auto-detect | Path to .env file |
| `TELEGRAM_SESSION_DIR` | No | Working directory | Directory for session file |
## How it works
This server uses the [Model Context Protocol](https://modelcontextprotocol.io/) to expose Telegram interaction as tools that any MCP-compatible AI client can use. Under the hood, it:
1. Connects to Telegram via MTProto using your pre-authenticated session
2. Sends messages to bots as your user account
3. Polls for replies and returns structured JSON responses
4. Disconnects cleanly after each operation
## Security notes
- Your session file (`telegram_user.session`) contains auth tokens — **never commit it**
- The `.gitignore` excludes session files by default
- API credentials should be passed via environment variables, not hardcoded
- This tool acts as YOUR Telegram account — treat it accordingly
## Development
```bash
git clone https://github.com/tensakulabs/telegram-mcp.git
cd telegram-mcp
uv sync
uv run telegram-mcp
```
## Requirements
- Python 3.10+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
## License
MIT
