Hermes-Skills/mcp/telegram-mcp/SKILL.md

name, description

name	description
telegram-mcp	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

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

First-time Login

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:

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):

  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:

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).