Content
---
title: Telegram MCP (personal, read-only)
emoji: 📬
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
license: apache-2.0
short_description: Personal Telegram MCP, read-only, bearer auth
---
# Telegram MCP — personal remote bridge
A self-hosted bridge that exposes [chigwell/telegram-mcp](https://github.com/chigwell/telegram-mcp) (Telethon-based) as a remote MCP server over streamable HTTP.
- **Userbot** — runs under your personal Telegram account via MTProto (Telethon), not the Bot API. No bot needed, no chat to add.
- **Read-only** — `TELEGRAM_EXPOSED_TOOLS=read-only`. Only the ~30 read tools are exposed (list chats, read messages, search, download media, etc.). Send/edit/delete/group-admin tools are not registered.
- **Bearer-token gated** — Caddy in front of the streamable HTTP server rejects every request without `Authorization: Bearer <MCP_BEARER_TOKEN>`.
## Endpoint
`https://francescomiliani-telegram-mcp.hf.space/mcp` (streamable HTTP, MCP spec 2025-03-26).
## Required Space secrets
Configure these in the Space's **Settings → Variables and secrets**:
| Name | Value | Where to get it |
|---|---|---|
| `TELEGRAM_API_ID` | int | https://my.telegram.org/apps |
| `TELEGRAM_API_HASH` | string | https://my.telegram.org/apps |
| `TELEGRAM_SESSION_STRING` | long base64-ish string | Generate locally with `uv run session_string_generator.py --qr` from chigwell/telegram-mcp |
| `MCP_BEARER_TOKEN` | long random string | `openssl rand -hex 32` |
`TELEGRAM_EXPOSED_TOOLS=read-only` is set as a default Space variable (not secret).
## Connecting from an MCP client
```bash
# Claude Code
claude mcp add --transport http telegram \
https://francescomiliani-telegram-mcp.hf.space/mcp \
--header "Authorization: Bearer $MCP_BEARER_TOKEN"
# Codex
codex mcp add telegram \
--url https://francescomiliani-telegram-mcp.hf.space/mcp \
--header "Authorization: Bearer $MCP_BEARER_TOKEN"
```
For stdio-only clients (Claude Desktop, some Windsurf builds), bridge through `mcp-remote`:
```json
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://francescomiliani-telegram-mcp.hf.space/mcp",
"--header", "Authorization: Bearer ${MCP_BEARER_TOKEN}"],
"env": { "MCP_BEARER_TOKEN": "<your-token>" }
}
}
}
```
## Security
- The Space URL is public. The bearer token is the only thing standing between the public internet and your Telegram account.
- Treat `TELEGRAM_SESSION_STRING` like a password — anyone with it can read/write your account.
- Free HF Spaces sleep after 48h of inactivity. The session is preserved (string-session mode), so the next request just wakes the container and reconnects. Expect a 20–40s cold start.
## Architecture
```
internet ──HTTPS──▶ Caddy :7860 ──(bearer check)──▶ main.py :8765 ──(Telethon/MTProto)──▶ Telegram
│ │
└─ 401 if no/bad bearer └─ streamable HTTP MCP, /mcp endpoint
```
