# 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