---

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 (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

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

{
  "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