{"id":49495185,"url":"https://github.com/mcp-telegram/mcp-telegram-cloud","last_synced_at":"2026-06-02T06:00:26.459Z","repository":{"id":354330727,"uuid":"1178786551","full_name":"mcp-telegram/mcp-telegram-cloud","owner":"mcp-telegram","description":"Open-source MCP server connecting Telegram to Claude AI and ChatGPT. Read messages, search chats, download media — read-only by design. Hosted free at mcp-telegram.com or self-host with Docker.","archived":false,"fork":false,"pushed_at":"2026-05-28T03:50:23.000Z","size":1697,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T04:20:35.312Z","etag":null,"topics":["chatgpt","claude-ai","gramjs","hono","mcp","model-context-protocol","mtproto","oauth","self-hostable","telegram","typescript"],"latest_commit_sha":null,"homepage":"https://mcp-telegram.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mcp-telegram.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-11T11:16:23.000Z","updated_at":"2026-05-28T03:50:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mcp-telegram/mcp-telegram-cloud","commit_stats":null,"previous_names":["mcp-telegram/mcp-telegram-cloud"],"tags_count":76,"template":false,"template_full_name":null,"purl":"pkg:github/mcp-telegram/mcp-telegram-cloud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcp-telegram%2Fmcp-telegram-cloud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcp-telegram%2Fmcp-telegram-cloud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcp-telegram%2Fmcp-telegram-cloud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcp-telegram%2Fmcp-telegram-cloud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcp-telegram","download_url":"https://codeload.github.com/mcp-telegram/mcp-telegram-cloud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcp-telegram%2Fmcp-telegram-cloud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33808702,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatgpt","claude-ai","gramjs","hono","mcp","model-context-protocol","mtproto","oauth","self-hostable","telegram","typescript"],"created_at":"2026-05-01T09:05:46.121Z","updated_at":"2026-06-02T06:00:26.416Z","avatar_url":"https://github.com/mcp-telegram.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Telegram Cloud\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n[![Hosted](https://img.shields.io/badge/hosted-mcp--telegram.com-2AABEE)](https://mcp-telegram.com)\n\nOpen source MCP server that connects a Telegram account to AI assistants\n(Claude.ai, ChatGPT) over OAuth + QR login. Hosted free at\n[mcp-telegram.com](https://mcp-telegram.com), or self-host on your own\ninfrastructure.\n\nThis is the **cloud / multi-user** flavour. For the single-user CLI\n(stdio transport, full read+write, all MTProto tools), use the upstream\n[`@overpod/mcp-telegram`](https://github.com/mcp-telegram/mcp-telegram).\n\n## What it does\n\n- Exposes a Telegram account to an MCP-aware client (Claude.ai, ChatGPT\n  Apps, custom MCP hosts) over Streamable HTTP.\n- **Read-only and safe-state-change tools only** — no `send-message`,\n  no `delete-message`, no admin actions. The hosted service trades off\n  capability for a smaller blast radius.\n- OAuth 2.0 with dynamic client registration and PKCE (RFC 8414 +\n  7591 + 7636). QR login is embedded in the OAuth authorize page —\n  connect once, reconnect via refresh token for 30 days.\n\n## Quick start (hosted)\n\n1. Open Claude.ai → Settings → Connectors → **Add custom connector**.\n2. Server URL: `https://mcp-telegram.com/mcp`.\n3. Click Connect. You will be redirected to scan a QR code with\n   Telegram (Settings → Devices → Link Desktop Device).\n4. Done. Ask Claude to read your unread messages, search chats, etc.\n\nChatGPT Apps Directory submission is in review. Until then, add\n`https://mcp-telegram.com/mcp` manually as a custom MCP server.\n\n## Quick start (self-hosted)\n\n```bash\ngit clone https://github.com/mcp-telegram/mcp-telegram-cloud.git\ncd mcp-telegram-cloud\ncp .env.example .env\n# fill in TELEGRAM_API_ID + TELEGRAM_API_HASH (from https://my.telegram.org/apps)\n# and ISSUER (your public HTTPS URL). ADMIN_TOKEN is optional but\n# recommended — without it admin-only operations on /api/* (stats,\n# operator-side session import) return 401.\ndocker compose -f docker-compose.example.yml up -d --build\n```\n\nThe example compose file binds to `127.0.0.1:3000` and **does not include\nTLS termination**. OAuth clients require HTTPS, so put a reverse proxy\nin front (Traefik, nginx + certbot, Caddy, managed LB). See\n[`docs/self-hosting.md`](./docs/self-hosting.md) for the threat model,\nhardening checklist, and incident response.\n\n\u003e ⚠️ The session database stores live MTProto session strings in\n\u003e plaintext. Read [`docs/self-hosting.md`](./docs/self-hosting.md)\n\u003e §Threat model before running this in production.\n\n## MCP tools exposed\n\nCloud whitelists a subset of the upstream tools. All are annotated\n`readOnlyHint: true` or are safe state-changes (mark-as-read, mute).\n\n**Read \u0026 search**\n\n- `telegram-status` — connection status\n- `telegram-list-chats` — dialogs with filtering\n- `telegram-read-messages` — paginated message read\n- `telegram-search-chats` — search chats by name / description / size\n- `telegram-search-global` — full-text search across public chats and\n  channels\n- `telegram-search-messages` — full-text search inside a chat\n- `telegram-get-unread` — unread chats with per-topic breakdown for\n  forums\n\n**Chat \u0026 member info**\n\n- `telegram-get-chat-info` — chat details and metadata\n- `telegram-get-chat-members` — group/channel members\n- `telegram-get-chat-folders` — user's chat folders\n- `telegram-list-topics` — forum topics with unread counts\n- `telegram-read-topic-messages` — read messages from a forum topic\n- `telegram-get-invite-links` — chat invite links\n- `telegram-get-reactions` — message reactions with user details\n\n**Profiles \u0026 contacts**\n\n- `telegram-get-profile` — detailed user profile (bio, photo, last\n  seen, premium)\n- `telegram-get-profile-photo` — download profile photo\n- `telegram-get-contacts` — contacts list\n- `telegram-get-contact-requests` — incoming non-contact messages\n\n**Stickers**\n\n- `telegram-get-sticker-set`\n- `telegram-search-sticker-sets`\n- `telegram-get-installed-stickers`\n- `telegram-get-recent-stickers`\n\n**Media**\n\n- `telegram-download-media` — download photos and documents\n\n**Safe state changes**\n\n- `telegram-mark-as-read` — mark a chat as read\n- `telegram-mute-chat` — mute notifications\n\n**Account info**\n\n- `telegram-get-sessions` — list active Telegram sessions\n\nFor the full upstream tool catalogue (including `send-message`,\n`forward-message`, group admin, profile write, etc.), use the CLI\n[`@overpod/mcp-telegram`](https://github.com/mcp-telegram/mcp-telegram).\n\n## Architecture\n\n- **Transport**: Streamable HTTP (`/mcp`)\n- **Auth**: OAuth 2.0 (RFC 8414 + 7591 + 7636/PKCE S256)\n- **Login**: QR via MTProto, embedded in OAuth authorize page\n- **Storage**: SQLite (sessions, OAuth tokens, usage log)\n- **Telegram client**: [`@overpod/mcp-telegram`](https://github.com/mcp-telegram/mcp-telegram)\n  via Master/Client IPC — each user runs in an isolated worker\n- **Pages**: Hono JSX (landing, OAuth authorize, privacy, terms)\n- **Observability**: structured logs to OTLP HTTP (SigNoz, Grafana\n  Cloud, etc.), or stderr if `SIGNOZ_ENDPOINT` is empty\n- **Deploy**: Docker. Production runs Docker Swarm + Traefik.\n\nSee [`docs/architecture.md`](./docs/architecture.md) for the component\nmap, request lifecycles, and storage layout.\n\n## Configuration\n\nAll runtime config is environment variables. Required:\n`TELEGRAM_API_ID`, `TELEGRAM_API_HASH`, `ISSUER`. `ADMIN_TOKEN` is\nrecommended — admin-only operations on `/api/*` (stats, operator-side\nsession import) return `401` without it.\n\nFull reference with required-vs-optional flags and change-impact\nwarnings: [`docs/configuration.md`](./docs/configuration.md).\n\n## Development\n\n```bash\npnpm install\ncp .env.example .env\npnpm dev          # tsx watch\npnpm test         # unit tests (node:test)\npnpm typecheck    # tsc --noEmit\npnpm lint         # biome\npnpm build        # tsc → dist/\n```\n\nThe pre-commit hook (`husky` + `biome check --staged`) runs Biome on\nstaged files and `gitleaks protect --staged` if Gitleaks is installed locally\n(`brew install gitleaks`). The same scan plus TruffleHog runs in CI on\nevery PR.\n\n## Contributing\n\nPRs welcome. Please read [`CONTRIBUTING.md`](./CONTRIBUTING.md) first —\nit covers the cloud-vs-upstream scope split, dev setup, and the\n\"won't merge\" list. By contributing you agree to the\n[Code of Conduct](./CODE_OF_CONDUCT.md). See [`ROADMAP.md`](./ROADMAP.md)\nfor what's planned, what's deferred, and what's explicitly out of scope.\n\nTool-level features (new `telegram-*` MCP tools, MTProto coverage)\nbelong in the upstream\n[`mcp-telegram`](https://github.com/mcp-telegram/mcp-telegram) repo.\nThis repo handles hosting concerns: OAuth, multi-user session storage,\nrate limiting, landing pages, ops.\n\n## Maintenance\n\nMaintained by **one person** in spare time. Expected response time on\nissues and PRs: ~2-3 days. No SLA, no paid support tier — but the\nhosted service is best-effort kept up.\n\nStatus updates land via the\n[@mcp_telegram_cloud_bot](https://t.me/mcp_telegram_cloud_bot) Telegram\nbot (subscribe via `/start`).\n\n## Security\n\nVulnerability disclosure: see [`SECURITY.md`](./SECURITY.md). Please\n**do not** open public issues for security problems.\n\n## License\n\n[MIT](./LICENSE) © overpod, 2025-2026.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcp-telegram%2Fmcp-telegram-cloud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcp-telegram%2Fmcp-telegram-cloud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcp-telegram%2Fmcp-telegram-cloud/lists"}