Telegram Mcp Server

---

title: Telegram MCP (personal, read-only) emoji: 📬 colorFrom: blue colorTo: green sdk: docker appport: 7860 pinned: false license: apache-2.0 shortdescription: 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 .

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": "" }
    }
  }
}

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: francescomiliani
• Source: francescomiliani/telegram-mcp-server
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.