# telegram-mcp-server

A **Telegram MCP server** via [Telethon](https://docs.telethon.dev/) — persistent client, flood-safe, 9 grouped tools.

**Zero API keys in code.** Session files stored locally. Works with user accounts (2FA) and bots.

---

## 1. Install

```bash
git clone <this-repo> telegram-mcp-server
cd telegram-mcp-server

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

pip install -e .
```

### Get your API credentials

1. Go to [my.telegram.org](https://my.telegram.org)
2. Log in with your phone number
3. Create an app → get **API ID** and **API Hash**

### One-time auth

```bash
# User account (with 2FA support)
export TG_API_ID=12345
export TG_API_HASH="your_hash_here"
telegram-mcp-server --auth --phone +33612345678

# Or via MCP tool: tg_session(action="auth", api_id=12345, api_hash="...", phone="+33612345678")
```

---

## 2. Register in your MCP client

### Claude Desktop / OpenCode

```json
{
  "mcpServers": {
    "telegram": {
      "command": "telegram-mcp-server",
      "env": {
        "TG_API_ID": "12345",
        "TG_API_HASH": "your_hash_here"
      }
    }
  }
}
```

If not on PATH:

```json
{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "telegram_mcp_server"],
      "env": {
        "TG_API_ID": "12345",
        "TG_API_HASH": "your_hash_here"
      }
    }
  }
}
```

### Docker

```bash
docker build -t telegram-mcp .
docker run -i --rm \
  -v ~/.telegram-mcp/sessions:/root/.telegram-mcp/sessions \
  -e TG_API_ID=12345 \
  -e TG_API_HASH="your_hash" \
  telegram-mcp
```

---

## 3. Tool catalog (9 tools, 8 actions)

### `tg_session` — Session management

| action | Required args | Description |
|--------|---------------|-------------|
| `auth` | `api_id`, `api_hash`, `phone` or `bot_token` | Authenticate (2FA supported) |
| `check` | — | Check login status |
| `logout` | — | Delete session |

### `tg_message` — Send, forward, delete, reply

| action | Required args | Description |
|--------|---------------|-------------|
| `send` | `target`, `text` | Send a message |
| `forward` | `target`, `message_id`, `to_target` | Forward a message |
| `delete` | `target`, `message_id` | Delete a message |
| `reply` | `target`, `message_id`, `text` | Reply to a message |

### `tg_chat` — Chat operations

| action | Required args | Description |
|--------|---------------|-------------|
| `list` | — | List recent chats |
| `info` | `target` | Get chat info |
| `members` | `target` | List chat members |
| `leave` | `target` | Leave a chat |

### `tg_search` — Search

| action | Required args | Description |
|--------|---------------|-------------|
| `messages` | `query` | Search messages (optionally in `target`) |
| `users` | `query` | Search contacts/users |
| `channels` | `query` | Search channels |

### `tg_history` — Chat history

| action | Required args | Description |
|--------|---------------|-------------|
| `messages` | `target` | Get message history |
| `media` | `target` | Get media-only history |
| `files` | `target` | Get file-only history |

### `tg_user` — User operations

| action | Required args | Description |
|--------|---------------|-------------|
| `me` | — | Get your own info |
| `info` | `target` | Get user info |
| `block` | `target` | Block a user |
| `unblock` | `target` | Unblock a user |

### `tg_media` — Send media

| action | Required args | Description |
|--------|---------------|-------------|
| `send_photo` | `target`, `file_path` | Send a photo |
| `send_video` | `target`, `file_path` | Send a video |
| `send_file` | `target`, `file_path` | Send a document |
| `send_voice` | `target`, `file_path` | Send a voice note |

### `tg_channel` — Channel management

| action | Required args | Description |
|--------|---------------|-------------|
| `create` | `title` | Create a supergroup/channel |
| `join` | `target` | Join a channel |
| `leave` | `target` | Leave a channel |
| `info` | `target` | Get channel info |

### `tg_draft` — Draft messages

| action | Required args | Description |
|--------|---------------|-------------|
| `save` | `target`, `text` | Save a draft |
| `list` | — | List all drafts |
| `delete` | `target` | Delete a draft |

---

## 4. Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `TG_API_ID` | `0` | Telegram API ID (from my.telegram.org) |
| `TG_API_HASH` | `""` | Telegram API Hash |
| `TG_SESSION_DIR` | `~/.telegram-mcp/sessions` | Session files location |

---

## 5. Safety

- **Rate limiter**: Send actions capped at 5/min. Read actions unlimited.
- **FloodWaitError auto-retry**: Waits the required time (capped at 5 min).
- **Session files**: Local only, never committed to git.
- **2FA support**: Full support for accounts with two-factor auth.

---

## 6. MCP resources

- `tg://version` — Server version
- `tg://session/status` — Login state

---

## License

MIT