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