convez.ai
MCP ServerIntegração & APIsIntermediário
mcp-telegram

MCP Telegram Cloud

mcp-telegram/mcp-telegram-cloud

Acesse Telegram via Claude AI e ChatGPT de forma segura e read-only

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor 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-cloud

1 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

Estrelas
13
Forks
11
Acompanhando
0
Saúde
87%
Último commit
há 1 dia
Versão
v2.67.2
Issues abertas
27
Contribuidores
1

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

License: MIT Hosted

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).
  4. 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 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 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.

Ver o original no GitHub

Bom para

Relacionados