Initial commit: Hermes Agent skills collection
- Trading skills (OKX, dividend, lottery, quantitative) - Creative skills (ASCII art, diagrams, video) - Development skills (GitHub, debugging, TDD) - Research skills (arXiv, blog monitoring) - Productivity skills (email, documents, notes) - MCP integration skills - Custom user skills
This commit is contained in:
Hermes Skills Manager
@@ -0,0 +1,148 @@
|
||||
---
|
||||
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).
|
||||
@@ -0,0 +1,74 @@
|
||||
# Telegram MCP Server Comparison (2026-06-15)
|
||||
|
||||
## Server Options Found on GitHub (sorted by popularity)
|
||||
|
||||
### 1. chaindead/telegram-mcp ⭐ 300+
|
||||
- **Language**: Go
|
||||
- **Auth**: MTProto (real account)
|
||||
- **Install**: `brew install chaindead/tap/telegram-mcp` or `go install` or binary
|
||||
- **Features**: Dialog list, unread messages, mark read, drafts, message retrieval, contacts, media download
|
||||
- **Transport**: stdio
|
||||
- **Pros**: Most popular, well-documented, cross-platform
|
||||
- **Cons**: Go binary (harder to debug/extend), requires Go 1.24+ for source install
|
||||
|
||||
### 2. sparfenyuk/mcp-telegram ⭐ active (RECOMMENDED)
|
||||
- **Language**: Python
|
||||
- **Auth**: MTProto (real account)
|
||||
- **Install**: `uv tool install git+https://github.com/sparfenyuk/mcp-telegram`
|
||||
- **Features**: Same as chaindead — dialogs, messages, contacts, media, drafts
|
||||
- **Transport**: stdio
|
||||
- **Pros**: Python (easy to extend), uv-based install, CLI sign-in flow
|
||||
- **Cons**: Less stars than chaindead; **pydantic-settings env var conflict** — sign-in command reads ALL `.env` vars and rejects unknowns. Use direct Telethon login instead (see `telethon-login.py`)
|
||||
|
||||
### 3. fast-mcp-telegram (leshchenko1979) ⭐ 46
|
||||
- **Language**: Python
|
||||
- **Auth**: MTProto (real account)
|
||||
- **Install**: `uv tool install fast-mcp-telegram`
|
||||
- **Features**: Production-grade, multi-user ACL, dual transport (stdio + HTTP SSE), voice transcription
|
||||
- **Transport**: stdio + HTTP SSE
|
||||
- **Pros**: Most feature-rich, ACL for multi-user, voice transcription
|
||||
- **Cons**: **Does NOT support SOCKS5 proxy** — only MTProto proxy (`tg://proxy`). Unusable on servers behind firewalls (e.g. China) that need SOCKS5/HTTP proxy to reach Telegram.
|
||||
|
||||
### 4. zhigang1992/telegram-mcp ⭐ 14
|
||||
- **Language**: TypeScript
|
||||
- **Auth**: MTProto
|
||||
- **Features**: Send/read/search messages, wait for incoming, conversation history
|
||||
- **Transport**: stdio
|
||||
|
||||
### 5. IQAIcom/mcp-telegram ⭐ 7
|
||||
- **Language**: TypeScript
|
||||
- **Auth**: Bot API (BotFather token)
|
||||
- **Features**: Send message, get channel info, forward, pin, get members
|
||||
- **Limitation**: Bot API only — cannot access contacts, personal chats, or global search
|
||||
- **Use case**: Channel/bot management, NOT personal account access
|
||||
|
||||
### 6. moltis ⭐ 2740
|
||||
- **Note**: Full agent platform (Rust), not a standalone MCP server
|
||||
- **Overkill** if you just want Telegram MCP
|
||||
|
||||
## Recommendation
|
||||
|
||||
**For Hermes integration (default)**: Use `sparfenyuk/mcp-telegram` (Python, uv install). Skip `mcp-telegram sign-in` due to pydantic env var conflict — use the direct Telethon login script instead.
|
||||
|
||||
**For firewalled servers (China, etc.)**: MUST use `sparfenyuk/mcp-telegram` — it's the only one supporting SOCKS5 proxy via `python-socks`. `fast-mcp-telegram` will fail to connect.
|
||||
|
||||
**Avoid** Bot API-based servers (like IQAIcom) if you need contacts, cross-chat search, or personal account access.
|
||||
|
||||
## Key Distinction: MTProto vs Bot API
|
||||
|
||||
| | MTProto | Bot API |
|
||||
|---|---|---|
|
||||
| Auth | Your real TG account | Bot token from @BotFather |
|
||||
| Contacts | ✅ | ❌ |
|
||||
| All chats | ✅ | Only where bot is added |
|
||||
| Global search | ✅ | ❌ |
|
||||
| Rate limits | Per-account | Per-bot (more lenient) |
|
||||
| Risk | Account suspension if abused | Low risk |
|
||||
|
||||
## Proxy Support Matrix
|
||||
|
||||
| Server | SOCKS5 | HTTP Proxy | MTProto Proxy |
|
||||
|---|---|---|---|
|
||||
| sparfenyuk/mcp-telegram | ✅ (python-socks) | ❌ | ❌ |
|
||||
| chaindead/telegram-mcp | ❓ | ❓ | ❓ |
|
||||
| fast-mcp-telegram | ❌ | ❌ | ✅ |
|
||||
@@ -0,0 +1,60 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Telegram MTProto login script for first-time authentication.
|
||||
Bypasses mcp-telegram's pydantic-settings env_file conflict.
|
||||
|
||||
Usage (user must run interactively via SSH):
|
||||
bash /tmp/tg_login.sh
|
||||
|
||||
The script will:
|
||||
1. Ask for phone number
|
||||
2. Send verification code to Telegram
|
||||
3. Prompt for code (type immediately when received)
|
||||
4. Handle 2FA if needed
|
||||
5. Save session for mcp-telegram to use
|
||||
"""
|
||||
import asyncio
|
||||
from telethon import TelegramClient
|
||||
from telethon.errors import SessionPasswordNeededError
|
||||
import socks
|
||||
import sys
|
||||
import os
|
||||
|
||||
# === Configuration ===
|
||||
# Update these or read from env
|
||||
API_ID = int(os.environ.get('TG_API_ID', '0'))
|
||||
API_HASH = os.environ.get('TG_API_HASH', '')
|
||||
SESSION_PATH = os.path.expanduser('~/.local/share/state/mcp-telegram/mcp_telegram_session')
|
||||
PROXY = (socks.SOCKS5, '127.0.0.1', 7890) # Mihomo
|
||||
|
||||
|
||||
async def main():
|
||||
if not API_ID or not API_HASH:
|
||||
print("Error: Set TG_API_ID and TG_API_HASH environment variables first.")
|
||||
print(" export TG_API_ID=your_id")
|
||||
print(" export TG_API_HASH=your_hash")
|
||||
sys.exit(1)
|
||||
|
||||
phone = input("Phone number (with country code, e.g. +1234567890): ").strip()
|
||||
|
||||
# Ensure session directory exists
|
||||
os.makedirs(os.path.dirname(SESSION_PATH), exist_ok=True)
|
||||
|
||||
client = TelegramClient(SESSION_PATH, API_ID, API_HASH, proxy=PROXY)
|
||||
|
||||
try:
|
||||
await client.start(phone=phone)
|
||||
except SessionPasswordNeededError:
|
||||
pwd = input("2FA password: ").strip()
|
||||
await client.sign_in(password=pwd)
|
||||
|
||||
me = await client.get_me()
|
||||
print(f"\n✅ Login successful!")
|
||||
print(f" User: {me.username} (ID: {me.id})")
|
||||
print(f" Session saved to: {SESSION_PATH}")
|
||||
print(f"\nYou can now use mcp-telegram MCP server.")
|
||||
await client.disconnect()
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
asyncio.run(main())
|
||||
@@ -0,0 +1,30 @@
|
||||
#!/bin/bash
|
||||
# Telegram MTProto login script
|
||||
# Run this via SSH: bash /tmp/tg_login.sh
|
||||
#
|
||||
# This bypasses the mcp-telegram CLI (which has pydantic-settings env conflicts)
|
||||
# and uses Telethon directly with SOCKS5 proxy.
|
||||
|
||||
/home/openclaw/.local/share/uv/tools/mcp-telegram/bin/python3 << 'EOF'
|
||||
import asyncio
|
||||
from telethon import TelegramClient
|
||||
from telethon.errors import SessionPasswordNeededError
|
||||
import socks
|
||||
|
||||
API_ID = 37679203
|
||||
API_HASH = '514a2ba8b7898365c9070da4739e8deb'
|
||||
SESSION = '/home/openclaw/.local/share/state/mcp-telegram/mcp_telegram_session'
|
||||
|
||||
async def main():
|
||||
phone = input("Phone (e.g. +1234567890): ").strip()
|
||||
client = TelegramClient(
|
||||
SESSION, API_ID, API_HASH,
|
||||
proxy=(socks.SOCKS5, '127.0.0.1', 7890)
|
||||
)
|
||||
await client.start(phone=phone)
|
||||
me = await client.get_me()
|
||||
print(f"\n✅ Logged in as: {me.username} (ID: {me.id})")
|
||||
await client.disconnect()
|
||||
|
||||
asyncio.run(main())
|
||||
EOF
|
||||
Reference in New Issue
Block a user