---
name: telegram-mcp
description: "Connect Telegram account to AI agent via MCP (Model Context Protocol). Read contacts, search messages across chats, manage dialogs, download media — full TG client capability. Use when user asks to view TG contacts, search messages in other chats, or interact with Telegram beyond the built-in bot channel."
---

# Telegram MCP Integration

Bridges the user's real Telegram account (MTProto API) to Hermes via MCP, unlocking capabilities the built-in bot channel cannot provide.

## When to Use

- User asks to view Telegram contacts
- User asks to search messages in chats OTHER than the current bot conversation
- User wants to read/manage Telegram dialogs (channels, groups, DMs)
- User wants to send messages from their personal TG account (not the bot)
- User wants to download media files from Telegram

## What Bot Channel Can vs Cannot Do

| Capability | Built-in Bot | MCP (MTProto) |
|---|---|---|
| Send to current chat | ✅ | ✅ |
| View contacts | ❌ | ✅ |
| Read any chat/dialog | ❌ | ✅ |
| Search messages globally | ❌ | ✅ |
| Download media | ❌ | ✅ |
| Draft messages | ❌ | ✅ |
| Mark as read | ❌ | ✅ |

## Recommended Server: sparfenyuk/mcp-telegram

**Repo**: https://github.com/sparfenyuk/mcp-telegram

Python-based, actively maintained, supports:
- Dialog list (chats, channels, groups)
- Unread message retrieval
- Message search by date/time
- Contact list
- Media download
- Draft messages
- Mark as read

### Prerequisites

1. **Telegram API credentials** from https://my.telegram.org/auth:
   - `TG_API_ID` (numeric)
   - `TG_API_HASH` (string)
   - These are DIFFERENT from a Bot Token — they authenticate your personal account

2. **Phone number** + 2FA password (if enabled) for first-time login

3. **Python** with `uv` tool installed

### Installation

```bash
uv tool install git+https://github.com/sparfenyuk/mcp-telegram
```

### First-time Login

```bash
mcp-telegram sign-in --api-id <your-api-id> --api-hash <your-api-hash> --phone-number <your-phone-number>
```

Enter the verification code from Telegram. Session is persisted.

### Hermes Integration (native-mcp)

Add to `~/.hermes/config.yaml` under `mcp_servers`:

```yaml
mcp_servers:
  telegram-mcp:
    command: mcp-telegram
    env:
      TG_API_ID: "your-api-id"
      TG_API_HASH: "your-api-hash"
```

Or load the `native-mcp` skill for detailed MCP setup instructions.

## Alternative Servers

| Server | Language | Stars | Notes |
|---|---|---|---|
| chaindead/telegram-mcp | Go | 300+ | Popular, brew install, but Go-based |
| fast-mcp-telegram (leshchenko1979) | Python | 46 | Production-grade, ACL, voice transcription |
| IQAIcom/mcp-telegram | TypeScript | 7 | Bot API based (not MTProto), limited |

**Prefer MTProto-based servers** (sparfenyuk, chaindead) over Bot API servers — they authenticate as your real account and can access contacts, all chats, search, etc.

## Pitfalls

- **API ID ≠ Bot Token**: my.telegram.org gives you API ID/Hash for MTProto (your account). @BotFather gives Bot Token. They are completely different auth mechanisms.
- **Session persistence**: First login creates a session file. If it expires, re-run `mcp-telegram sign-in`.
- **Rate limits**: Telegram enforces API rate limits. Don't spam requests.
- **Privacy**: MTProto gives full account access. Only use on trusted machines.
- **Mihomo proxy**: If TG is blocked, set proxy via env or the MCP server's proxy config.
- **pydantic-settings env_file conflict**: `TelegramSettings` uses `env_file = ".env"` which reads ALL vars from the `.env` file, not just `TELEGRAM_*` prefixed ones. If other env vars exist (e.g. `LONGBRIDGE_*`), pydantic's `extra=forbid` rejects them with `ValidationError: Extra inputs are not permitted`. **Fix**: unset conflicting vars before running sign-in, or write a custom Telethon script bypassing pydantic entirely.
- **python-socks vs pysocks**: Telethon requires `python-socks[asyncio]` (NOT `pysocks`) for SOCKS5 proxy support. Install into the uv tool venv: `uv pip install --python ~/.local/share/uv/tools/mcp-telegram/bin/python3 python-socks[asyncio]`
- **Verification code expiry (~30s)**: Telegram MTProto codes expire very quickly. The round-trip of "send code → user reads on phone → tells agent → agent submits" via chat almost always exceeds the window. **Recommended**: Have the user SSH into the server and run the sign-in script directly in an interactive terminal. The script should use `client.start(phone=phone)` which handles the prompt interactively.
- **Sign-in script template** (for user to run via SSH):
  ```python
  from telethon import TelegramClient
  import socks
  client = TelegramClient('/path/to/session', API_ID, API_HASH, proxy=(socks.SOCKS5, '127.0.0.1', 7890))
  await client.start(phone='+XXXXXXXX')
  ```
- **fast-mcp-telegram alternative**: Installed via `uv tool install fast-mcp-telegram`. Has better auth flow features but does NOT support SOCKS5 proxy (only MTProto proxy), making it unusable behind Mihomo/Clash. Stick with sparfenyuk/mcp-telegram + python-socks.
### ⚠️ `mcp-telegram sign-in` env var conflict (CRITICAL)

`TelegramSettings` uses `pydantic-settings` with `env_file = ".env"` and `extra = "forbid"`. It reads ALL variables from `~/.hermes/.env` (or CWD `.env`), not just `TELEGRAM_*` prefixed ones. If you have other env vars (e.g. `LONGBRIDGE_*`, `OKX_*`), the sign-in command crashes with `ValidationError: Extra inputs are not permitted`.

**Fix**: Do NOT use `mcp-telegram sign-in`. Use the direct Telethon login script instead (see `references/telethon-login.py`). It bypasses pydantic-settings entirely.

### ⚠️ Verification code expiry (CRITICAL)

Telegram codes expire in ~30 seconds. The round-trip of "send code → user reads on phone → user tells agent → agent submits" almost always exceeds this window.

**Fix**: User MUST SSH into the server and run the login script directly in a terminal. They type the code immediately when prompted — zero round-trip delay. Copy the script from `references/telethon-login.py` to `/tmp/tg_login.sh` and tell user to `bash /tmp/tg_login.sh`.

### ⚠️ SOCKS5 proxy for firewalled servers

Telethon needs `python-socks` (NOT `pysocks`) for SOCKS5 proxy support. After installing `mcp-telegram`, also install:

```bash
uv pip install --python $(which mcp-telegram | sed 's|/bin/mcp-telegram|/bin/python3|') python-socks[asyncio]
```

`fast-mcp-telegram` does NOT support SOCKS5 proxy — it only supports MTProto proxy (`tg://proxy`). Do not use it on servers behind firewalls.

### ⚠️ Phone number masking in Hermes

Hermes auto-detects and masks phone numbers in tool output (e.g. `+172****0777`). If you need to pass a phone number to a script, store it in a file first (the file content is not masked), then read it from the script.

### ⚠️ Login must happen interactively

The `mcp-telegram sign-in` command uses `input()` which fails in non-interactive terminal contexts. Background processes and `pty` mode also cannot reliably provide stdin. The ONLY reliable approach is direct SSH access.

### ⚠️ API credential masking in terminal writes

Hermes auto-masks API keys, secrets, and tokens in tool output and file writes. If you need to write OKX/TG credentials to `~/.bashrc`, the values get replaced with `***`. Workaround: tell the user to run the `cat >> ~/.bashrc` command themselves in a direct terminal session. Never try to write credentials through tools — it silently produces truncated values.

## References

See `references/server-comparison.md` for detailed feature comparison of all Telegram MCP servers.
See `references/telethon-login.sh` for a ready-to-use login script (bypasses pydantic-settings env conflict).