# Telegram MCP Servers

Extend Hermes with full Telegram account access (contacts, messages, search, media) via MCP.

## Top Options (ranked)

### 1. chaindead/telegram-mcp ⭐ RECOMMENDED
- **GitHub**: https://github.com/chaindead/telegram-mcp
- **Language**: Go
- **Auth**: MTProto (your real TG account, NOT bot)
- **Stars**: 330+
- **Install**: `brew install chaindead/tap/telegram-mcp` or `npx -y @chaindead/telegram-mcp` or `go install github.com/chaindead/telegram-mcp@latest`
- **Features**: Dialog listing, message retrieval, unread filtering, mark as read, draft messages, contacts, media download
- **Env vars**: `TG_APP_ID`, `TG_APP_HASH` (from https://my.telegram.org/auth)
- **Config for Hermes**:
  ```yaml
  mcp_servers:
    telegram:
      command: "npx"
      args: ["-y", "@chaindead/telegram-mcp"]
      env:
        TG_APP_ID: "your_api_id"
        TG_APP_HASH: "your_api_hash"
  ```

### 2. sparfenyuk/mcp-telegram
- **GitHub**: https://github.com/sparfenyuk/mcp-telegram
- **Language**: Python
- **Auth**: MTProto (real account)
- **Install**: `uv tool install git+https://github.com/sparfenyuk/mcp-telegram`
- **Features**: Dialog list, messages by date, unread messages, contacts, media download, draft messages, mark as read
- **Setup**: Requires first-time sign-in:
  ```bash
  mcp-telegram sign-in --api-id <ID> --api-hash <HASH> --phone-number <PHONE>
  ```
- **Config for Hermes**:
  ```yaml
  mcp_servers:
    telegram:
      command: "mcp-telegram"
      args: ["serve"]
  ```

### 3. fast-mcp-telegram (leshchenko1979)
- **GitHub**: https://github.com/leshchenko1979/fast-mcp-telegram
- **Stars**: 46
- **Features**: MTProto, multi-user ACL, dual transport (stdio + HTTP SSE), voice transcription
- **Install**: `uvx fast-mcp-telegram`

### 4. Bot API based (mcp-server-telegram)
- **Install**: `pip install mcp-server-telegram`
- **Auth**: Bot token from @BotFather
- **Limitation**: Bots CANNOT read arbitrary user DMs, no contacts, no search
- **Use case**: Notification bots, broadcast only

## Recommendation

**Use chaindead/telegram-mcp** for full account access. It's Go-based (fast), well-maintained, and supports contacts + message search + media download — exactly what was needed to "查看TG联系人" and "搜索聊天记录".

### Prerequisites
1. Get API credentials: https://my.telegram.org/auth → API development tools
2. Note: This is separate from Bot tokens. MTProto API gives full user-account access.

### Security Note
MCP server gets full read access to your Telegram account. Only install servers you trust. The `env` config ensures credentials aren't leaked to other servers.