MCP Telegram Cloud
mcp-telegram/mcp-telegram-cloud
Acesse Telegram via Claude AI e ChatGPT de forma segura e read-only
Ver no GitHubServidor MCP que conecta uma conta Telegram ao Claude AI e ChatGPT via OAuth + login por QR code. Oferece leitura de mensagens, busca em chats, download de mídia — totalmente read-only por design. Disponível gratuitamente em mcp-telegram.com ou para auto-hospedagem com Docker.
Instalação
npx convez-ai mcp-telegram/mcp-telegram-cloud1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Ler mensagens não lidas e buscar em chats diretamente do Claude
- Pesquisar conteúdo em grupos e canais via IA
- Integrar Telegram como fonte de dados para análise e contexto em conversas
Veredito

Solução bem arquitetada para leitura de Telegram em assistentes IA, com foco em segurança (read-only) e facilidade de deploy. Útil para quem quer contexto de Telegram no Claude sem riscos de modificação acidental de dados.
README
A tradução para o português deste README ainda está na fila.
MCP Telegram Cloud
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, nodelete-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)
- Open Claude.ai → Settings → Connectors → Add custom connector.
- Server URL:
https://mcp-telegram.com/mcp. - Click Connect. You will be redirected to scan a QR code with Telegram (Settings → Devices → Link Desktop Device).
- 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 for the threat model,
hardening checklist, and incident response.
⚠️ The session database stores live MTProto session strings in plaintext. Read
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 statustelegram-list-chats— dialogs with filteringtelegram-read-messages— paginated message readtelegram-search-chats— search chats by name / description / sizetelegram-search-global— full-text search across public chats and channelstelegram-search-messages— full-text search inside a chattelegram-get-unread— unread chats with per-topic breakdown for forums
Chat & member info
telegram-get-chat-info— chat details and metadatatelegram-get-chat-members— group/channel memberstelegram-get-chat-folders— user's chat folderstelegram-list-topics— forum topics with unread countstelegram-read-topic-messages— read messages from a forum topictelegram-get-invite-links— chat invite linkstelegram-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 phototelegram-get-contacts— contacts listtelegram-get-contact-requests— incoming non-contact messages
Stickers
telegram-get-sticker-settelegram-search-sticker-setstelegram-get-installed-stickerstelegram-get-recent-stickers
Media
telegram-download-media— download photos and documents
Safe state changes
telegram-mark-as-read— mark a chat as readtelegram-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-telegramvia 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_ENDPOINTis empty - Deploy: Docker. Production runs Docker Swarm + Traefik.
See 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.
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 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. See 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
@mcp_telegram_cloud_bot Telegram
bot (subscribe via /start).
Security
Vulnerability disclosure: see SECURITY.md. Please
do not open public issues for security problems.
License
MIT © overpod, 2025-2026.