# Telegram Mcp Server

> Telegram MCP server — personal Telegram bridge over MCP protocol

- **Type:** MCP server
- **Install:** `agentstack add mcp-francescomiliani-telegram-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [francescomiliani](https://agentstack.voostack.com/s/francescomiliani)
- **Installs:** 0
- **Category:** [Communication](https://agentstack.voostack.com/c/communication)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [francescomiliani](https://github.com/francescomiliani)
- **Source:** https://github.com/francescomiliani/telegram-mcp-server

## Install

```sh
agentstack add mcp-francescomiliani-telegram-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

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

## 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](https://github.com/francescomiliani)
- **Source:** [francescomiliani/telegram-mcp-server](https://github.com/francescomiliani/telegram-mcp-server)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-francescomiliani-telegram-mcp-server
- Seller: https://agentstack.voostack.com/s/francescomiliani
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.