Mcp Telegram Cloud

MCP Telegram Cloud

[](./LICENSE) [](https://mcp-telegram.com)

Open source MCP server that connects a Telegram account to AI assistants (Claude.ai, ChatGPT) over OAuth + QR login. Hosted free at mcp-telegram.com, or self-host on your own infrastructure.

This is the cloud / multi-user flavour. For the single-user CLI (stdio transport, full read+write, all MTProto tools), use the upstream @overpod/mcp-telegram.

What it does

• Exposes a Telegram account to an MCP-aware client (Claude.ai, ChatGPT

Apps, custom MCP hosts) over Streamable HTTP.

• Read-only and safe-state-change tools only — no send-message,

no delete-message, no admin actions. The hosted service trades off capability for a smaller blast radius.

• OAuth 2.0 with dynamic client registration and PKCE (RFC 8414 +

7591 + 7636). QR login is embedded in the OAuth authorize page — connect once, reconnect via refresh token for 30 days.

Quick start (hosted)

1. Open Claude.ai → Settings → Connectors → Add custom connector.
2. Server URL: https://mcp-telegram.com/mcp.
3. Click Connect. You will be redirected to scan a QR code with

Telegram (Settings → Devices → Link Desktop Device).

1. Done. Ask Claude to read your unread messages, search chats, etc.

ChatGPT Apps Directory submission is in review. Until then, add https://mcp-telegram.com/mcp manually as a custom MCP server.

Quick start (self-hosted)

git clone https://github.com/mcp-telegram/mcp-telegram-cloud.git
cd mcp-telegram-cloud
cp .env.example .env
# fill in TELEGRAM_API_ID + TELEGRAM_API_HASH (from https://my.telegram.org/apps)
# and ISSUER (your public HTTPS URL). ADMIN_TOKEN is optional but
# recommended — without it admin-only operations on /api/* (stats,
# operator-side session import) return 401.
docker compose -f docker-compose.example.yml up -d --build

The example compose file binds to 127.0.0.1:3000 and does not include TLS termination. OAuth clients require HTTPS, so put a reverse proxy in front (Traefik, nginx + certbot, Caddy, managed LB). See [docs/self-hosting.md](./docs/self-hosting.md) for the threat model, hardening checklist, and incident response.

> ⚠️ The session database stores live MTProto session strings in > plaintext. Read [docs/self-hosting.md](./docs/self-hosting.md) > §Threat model before running this in production.

MCP tools exposed

Cloud whitelists a subset of the upstream tools. All are annotated readOnlyHint: true or are safe state-changes (mark-as-read, mute).

Read & search

• telegram-status — connection status
• telegram-list-chats — dialogs with filtering
• telegram-read-messages — paginated message read
• telegram-search-chats — search chats by name / description / size
• telegram-search-global — full-text search across public chats and

channels

• telegram-search-messages — full-text search inside a chat
• telegram-get-unread — unread chats with per-topic breakdown for

forums

Chat & member info

• telegram-get-chat-info — chat details and metadata
• telegram-get-chat-members — group/channel members
• telegram-get-chat-folders — user's chat folders
• telegram-list-topics — forum topics with unread counts
• telegram-read-topic-messages — read messages from a forum topic
• telegram-get-invite-links — chat invite links
• telegram-get-reactions — message reactions with user details

Profiles & contacts

• telegram-get-profile — detailed user profile (bio, photo, last

seen, premium)

• telegram-get-profile-photo — download profile photo
• telegram-get-contacts — contacts list
• telegram-get-contact-requests — incoming non-contact messages

Stickers

• telegram-get-sticker-set
• telegram-search-sticker-sets
• telegram-get-installed-stickers
• telegram-get-recent-stickers

Media

• telegram-download-media — download photos and documents

Safe state changes

• telegram-mark-as-read — mark a chat as read
• telegram-mute-chat — mute notifications

Account info

• telegram-get-sessions — list active Telegram sessions

For the full upstream tool catalogue (including send-message, forward-message, group admin, profile write, etc.), use the CLI @overpod/mcp-telegram.

Architecture

• Transport: Streamable HTTP (/mcp)
• Auth: OAuth 2.0 (RFC 8414 + 7591 + 7636/PKCE S256)
• Login: QR via MTProto, embedded in OAuth authorize page
• Storage: SQLite (sessions, OAuth tokens, usage log)
• Telegram client: @overpod/mcp-telegram

via Master/Client IPC — each user runs in an isolated worker

• Pages: Hono JSX (landing, OAuth authorize, privacy, terms)
• Observability: structured logs to OTLP HTTP (SigNoz, Grafana

Cloud, etc.), or stderr if SIGNOZ_ENDPOINT is empty

• Deploy: Docker. Production runs Docker Swarm + Traefik.

See [docs/architecture.md](./docs/architecture.md) for the component map, request lifecycles, and storage layout.

Configuration

All runtime config is environment variables. Required: TELEGRAM_API_ID, TELEGRAM_API_HASH, ISSUER. ADMIN_TOKEN is recommended — admin-only operations on /api/* (stats, operator-side session import) return 401 without it.

Full reference with required-vs-optional flags and change-impact warnings: [docs/configuration.md](./docs/configuration.md).

Development

pnpm install
cp .env.example .env
pnpm dev          # tsx watch
pnpm test         # unit tests (node:test)
pnpm typecheck    # tsc --noEmit
pnpm lint         # biome
pnpm build        # tsc → dist/

The pre-commit hook (husky + biome check --staged) runs Biome on staged files and gitleaks protect --staged if Gitleaks is installed locally (brew install gitleaks). The same scan plus TruffleHog runs in CI on every PR.

Contributing

PRs welcome. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) first — it covers the cloud-vs-upstream scope split, dev setup, and the "won't merge" list. By contributing you agree to the [Code of Conduct](./CODEOFCONDUCT.md). See [ROADMAP.md](./ROADMAP.md) for what's planned, what's deferred, and what's explicitly out of scope.

Tool-level features (new telegram-* MCP tools, MTProto coverage) belong in the upstream mcp-telegram repo. This repo handles hosting concerns: OAuth, multi-user session storage, rate limiting, landing pages, ops.

Maintenance

Maintained by one person in spare time. Expected response time on issues and PRs: ~2-3 days. No SLA, no paid support tier — but the hosted service is best-effort kept up.

Status updates land via the @mcptelegramcloud_bot Telegram bot (subscribe via /start).

Security

Vulnerability disclosure: see [SECURITY.md](./SECURITY.md). Please do not open public issues for security problems.

License

[MIT](./LICENSE) © overpod, 2025-2026.

Source & license

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

• Author: mcp-telegram
• Source: mcp-telegram/mcp-telegram-cloud
• License: MIT
• Homepage: https://mcp-telegram.com

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