Telegram MCP
Reads and sends messages in explicitly authorized Telegram chats and topics via a dedicated bot, with tools for checking status (telegram_status), reading stored inbox messages (telegram_read), and sending messages to configured destinations (telegram_send). Access is scoped per client credential and per destination, with no background polling and no instruction execution from message content.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Telegram MCP: self-hosted Cloudflare Worker
Explicit message reading and authorized sending; no wake/background polling, no instruction execution from messages. Config files only, no management UI. Dedicated Telegram bot and dedicated database required.
What is and is not ready
This standalone entry point validates per-client bearer credentials before deriving the caller identity. Public oai-authenticated-* headers are ignored. NEVER deploy worker/index.js directly: its identity contract is Sites-only. Wrangler uses worker/standalone.js.
Tested locally with Node mock HTTP and SQLite. Not deployed/tested on your Cloudflare account or against a real Telegram bot. No OAuth authorization server is implemented. This supports HTTP MCP clients that securely supply Authorization: Bearer. The local Plugin Creator package schema accepts API-key/Bearer metadata (see below), matching this server. However, the public OpenAI authentication guide states ChatGPT cannot present custom API keys. These are conflicting package-vs-runtime signals: schema acceptance does NOT prove this Dot can connect. End-to-end connection remains untested. OAuth may be required for the target host; it is NOT implemented here. Never select unauthenticated access or put credentials in URL query/path.
Related MCP server: Telegram MCP — Next Generation
Deploy yourself
Use a current Node LTS supporting node:sqlite for tests and official Wrangler v4.
npm test
npx wrangler@4 login
npx wrangler@4 d1 create telegram-mcpCopy returned database_id into wrangler.jsonc. Review the account, Worker name and costs. Config starts disabled with no destinations. Keep it disabled until all steps and client authentication are checked.
npx wrangler@4 d1 migrations apply telegram-mcp --remote
npx wrangler@4 deploy
npx wrangler@4 secret put TELEGRAM_BOT_TOKEN
npx wrangler@4 secret put MCP_CLIENT_OWNERAt the first secret prompt, paste the dedicated bot's BotFather token locally. At the second, paste a freshly generated 32-byte base64url random key from a password manager or your own terminal. No secrets go into chat, Git, wrangler.jsonc, screenshots, command arguments, or exported logs. Keep the client key in your client's secure credential store. These are DIFFERENT secrets; never use the Telegram token as the MCP credential.
Client key must be 43–128 base64url characters. Generate a separate key per client and map its secret environment name in config/clients.js. Secret names use MCP_CLIENT_ prefix. Replacing/deleting a secret revokes that client's previous key. Never share one key across people who need distinct group access.
Configure access
Edit config/destinations.js. Example:
personal: {
chatId: '123456789',
description: 'My private bot chat',
purpose: 'My requested messages and notifications',
canRead: true,
canSend: true,
allowedCallerIds: ['owner']
}Use the actual numeric chat ID, not a username; optional threadId targets exactly one topic. IDs and purposes are non-secret configuration. Add only chats the owner has authorized. After checking permissions, set enabled:true and run npx wrangler@4 deploy. This does not send messages or poll automatically.
For multiple users, add a distinct principal/secret in config/clients.js, then list that principal only on approved destinations. This authenticates MCP clients, NOT people who send Telegram messages. Sharing the same key means sharing the same permissions. No Telegram group member gains authority over the assistant by sending a message.
Candidate plugin metadata, NOT a verified Dot connection
The documented portable plugin schema supports:
"extensions": {
"com.openai": {
"auth": {"type": "api_key", "headerScheme": "bearer"}
}
}This belongs under the individual remote server in mcp.json, not at the top level. No key belongs in the package.
After obtaining your actual deployed URL, generate a credential-free package:
node scripts/make-plugin.mjs https://YOUR-ACTUAL-WORKER-HOST/mcp
tar -czf telegram-mcp-plugin.tar.gz telegram-mcp-pluginGive the assistant the actual non-secret endpoint and package, not your keys. It can verify the endpoint and create the private plugin through the supported plugin workflow. Only if the platform actually offers supported API-key credential entry, enter the MCP client key (same value as MCP_CLIENT_OWNER), never your Telegram bot token. The exact connection UI and end-to-end Dot invocation remain untested until a real endpoint exists. Public OpenAI docs: https://developers.openai.com/plugins/build/auth (Client identification) currently state custom API keys cannot be presented by ChatGPT; treat this candidate manifest as unverified, not a ready-to-install solution. If the platform offers no supported credential-entry control, stop rather than paste the key into conversation or put it into manifest/URL. Plugin creation alone does not prove successful authentication.
Verify without posting a message
Use your HTTP MCP client's secure bearer-header setting and the deployed HTTPS URL ending /mcp. Call telegram_status; ensure only that credential's aliases are listed. Missing/wrong credentials must return HTTP 401, even with a forged oai-authenticated-user-id header. Check telegram_read only after you authorize the destination's contents to be read. Test send only to an explicitly authorized recipient with a stated harmless test message. Never blindly retry an unknown receipt.
Data and operational limits
Dedicated bot: do not share getUpdates consumer or configure webhook; this Worker refuses an existing webhook, never removes it.
Telegram holds pending updates up to 24 hours; no arbitrary older chat history. Privacy mode limits visible group messages; disabling it increases collection and must be intentional.
A poll necessarily receives bot-wide updates in process memory. Only configured chat/topics are persisted/returned. Keep bot out of unapproved groups.
Inbox text/captions are stored in your D1 database indefinitely in this version. Choose retention before sustained use. No attachment downloads.
Read operation advances the bot queue only after storage; concurrent callers share one guarded cursor.
Receipt store reduces duplicate sends but ambiguous network failures remain unknown. No guarantee of exactly once.
Observability is disabled in wrangler.jsonc. Do not log headers, token-bearing Telegram URLs, message bodies or secrets. Hosting-provider telemetry is outside this application's control.
Start with a new D1 database. Do not reuse the database for another bot.
Monitor your own Cloudflare usage/costs. Add operational rate controls before sharing widely. No broad-production security audit has been performed.
Reference: https://developers.cloudflare.com/workers/configuration/secrets/ Reference: https://developers.cloudflare.com/d1/wrangler-commands/
Pagination cursors are local ordinals within each chat/topic, not bot-wide Telegram update IDs or global database sequences. They remain stable while earlier records are retained. Future retention/deletion work must preserve or replace that contract. Computing these ordinals scans the selected chat; large inboxes need indexing/retention design before production-scale use.
Open-source status
Experimental release under MIT. See SECURITY.md for hosting trust and known operational gaps. The bearer-key manifest is a candidate connection configuration, not evidence of successful Dot integration. Do not publish credentials to Issues or PRs.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Unofficial Telegram MCP server — read, search, reply and react in your own Telegram account.
Schedule posts, read analytics and manage Telegram channels in TGStudio from any MCP client.
Hosted Telegram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables sending and receiving Telegram messages through MCP clients like Claude Desktop and Gemini Spark.35 npmMIT
- AlicenseAqualityBmaintenanceEnables MCP-compatible clients to securely access and manage Telegram accounts, chats, messages, media, and contacts, with tiered permissions, write controls, and local caching.22Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients like Codex or ChatGPT to securely receive, acknowledge, and send Telegram messages with durable delivery guarantees and idempotency.MIT
- AlicenseNot gradedqualityBmaintenanceEnables sending and reading Telegram messages through MCP, using either a bot or a personal user account.636 npmMIT