Sends notification messages to Telegram chats with support for Markdown and HTML formatting, allowing AI agents to deliver task completion updates, error notifications, and status messages through Telegram bots.
Telegram Notification MCP Server
An MCP (Model Context Protocol) server that sends notifications to Telegram when Claude Code completes tasks. Built with TypeScript using the Cloudflare Agents SDK and deployable on Cloudflare Workers.
Features
- 🤖 MCP Tool: Provides a
send_telegram_message
tool for sending notifications - 🚀 Cloudflare Workers: Runs serverless with global distribution
- 🔐 Secure: Uses Cloudflare secrets for credentials
- 🌐 Dual Transport: Supports both SSE and Streamable HTTP for maximum compatibility
- 💾 Durable Objects: State management required by McpAgent
- 💬 Message Formatting: Supports Markdown and HTML formatting
- 📝 Formatting: Supports Markdown and HTML message formatting
Architecture
This server implements the MCP specification using Cloudflare's Agents SDK:
- GET /sse: SSE endpoint for MCP communication
- POST /mcp: Streamable HTTP endpoint for MCP communication
- Built with TypeScript, MCP SDK, and Cloudflare Agents SDK
- Proper JSON-RPC 2.0 error handling
- Durable Objects for stateful connections (required by McpAgent)
- Node.js compatibility mode enabled
Setup
Prerequisites
- Telegram Bot: Create a bot via @BotFather and get your bot token
- Chat ID: Get your chat ID by sending a message to your bot and visiting:
- Cloudflare Account: Sign up at cloudflare.com
Installation
- Clone this repository
- Install dependencies:
Configuration
- Create a
.dev.vars
file from the example:Then edit.dev.vars
with your bot token and chat ID. This file is used for both local development and deployment. - For production deployment, set up Cloudflare secrets:Note: The DEFAULT_CHAT_ID is optional. If not set, you must provide a chat_id parameter when calling the
send_telegram_message
tool. - Update
wrangler.toml
with your worker name if desired
Deployment
Deploy to Cloudflare Workers:
Deploy using Wrangler:
Alternative: Continuous Deployment
You can also set up continuous deployment directly from the cloudflare dashboard. Learn more about git integration with cloudflare
Claude Code Configuration
Add the MCP server to Claude Code using the CLI via SSE transport:
Note: This server supports both SSE (Server-Sent Events) and Streamable HTTP transport. While SSE works well, Streamable HTTP provides better reliability and is the newer standard.
You can verify the configuration with:
Usage
Once configured, Claude Code can send notifications to your Telegram whenever you need them.
Available Tool
send_telegram_message: Send a notification message to Telegram
text
(required): The message text to sendchat_id
(optional): Telegram chat ID (uses DEFAULT_CHAT_ID if not provided)parse_mode
(optional): "Markdown" or "HTML" for message formattingdisable_notification
(optional): Send message silently
Example usage:
When You'll Get Notifications
Claude Code sends notifications when:
- You explicitly ask: "notify me when done" or "let me know on Telegram"
- Errors occur during execution
- Important milestones are reached
- User input or intervention is needed
Example Scenarios
Example Notifications
CLAUDE.md Examples
To encourage Claude Code to use Telegram notifications effectively, add these to your CLAUDE.md:
Development
Run locally:
For local development, Wrangler will automatically load environment variables from your .dev.vars
file.
Run all checks before deployment:
This command runs:
pnpm format
- Format code with Biomepnpm lint:fix
- Fix linting issuespnpm cf-typegen
- Generate Cloudflare typespnpm type-check
- Check TypeScript types
Test the server:
Debugging
Testing the SSE Connection
You can test the SSE endpoint directly:
This should return an event stream starting with an endpoint
event.
Common Issues
- Connection closes immediately: Check that your worker is running and accessible at the specified URL.
- No endpoint event received: Ensure the SSE headers are being sent correctly and the stream is properly formatted.
- Telegram notifications not sent: Verify your
BOT_TOKEN
andDEFAULT_CHAT_ID
are correctly set in the worker environment.
Technical Details
- Language: TypeScript (ES2021 target)
- Runtime: Cloudflare Workers with Node.js compatibility
- Protocol: MCP (Model Context Protocol)
- Transport: SSE and Streamable HTTP
- State Management: Durable Objects (required by McpAgent)
- Observability: Enabled for monitoring
References
This project was built following these guides:
- Build a Remote MCP server - Cloudflare Agents
- Model Context Protocol (MCP) - Cloudflare Agents
- MCP Transport Methods - Cloudflare Agents
- Cloudflare MCP Template (remote-mcp-authless)
Related Projects
- Discord Notification MCP - Send notifications to Discord instead of Telegram
License
MIT
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables Claude Code to send Telegram notifications when tasks complete, errors occur, or user intervention is needed. Runs serverless on Cloudflare Workers with support for formatted messages and flexible chat targeting.
Related MCP Servers
- AsecurityAlicenseAqualityA tool integration that enables Claude to compose and send emails through the Resend API, supporting features like scheduled delivery and file attachments.Last updated -16173JavaScriptMIT License
- -securityAlicense-qualityA server that enables interaction with Telegram chats directly through MCP-compatible hosts like Claude for Desktop, providing tools to retrieve chats, get messages, and send messages.Last updated -272PythonApache 2.0
- -securityAlicense-qualityA simple MCP server that allows Claude to access your Telegram account to read and send messages on your behalf.Last updated -6PythonApache 2.0
- -securityAlicense-qualityEnables interactions with Google Cloud Tasks queues and tasks through natural language, allowing users to list, manage, pause/resume queues and handle tasks via Claude Desktop.Last updated -JavaScriptMIT License