š¤ A Model Context Protocol (MCP) server that provides Telegram messaging capabilities via Server-Sent Events (SSE). Send messages to Telegram through any MCP-compatible client like Cursor, Claude Desktop, or custom applications.
/newbotSend a message to your bot, then visit:
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
Look for chat.id in the response.
Create a .env file:
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here
Create docker-compose.yml:
services:
telegram-mcp:
image: mcp-telegram-server
build: .
ports:
- "8008:8008"
environment:
- TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
- TELEGRAM_CHAT_ID=${TELEGRAM_CHAT_ID}
- HOST=0.0.0.0
- PORT=8008
env_file:
- .env
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8008/"]
interval: 30s
timeout: 10s
retries: 3
Start the server:
docker-compose up -d
Add to your MCP settings:
{
"mcpServers": {
"telegram": {
"url": "http://localhost:8008/sse"
}
}
}
Add to claude_desktop_config.json:
{
"mcpServers": {
"telegram": {
"url": "http://localhost:8008/sse"
}
}
}
Send a text message to your configured Telegram chat.
Parameters:
message (required): The text message to sendparse_mode (optional): "Markdown", "MarkdownV2", or "HTML"Example:
{
"message": "Hello from MCP! š\n\n**Bold text** and *italic text*",
"parse_mode": "Markdown"
}
| Variable | Description | Required | Default |
|---|---|---|---|
TELEGRAM_BOT_TOKEN | Your Telegram bot token from BotFather | ā Yes | - |
TELEGRAM_CHAT_ID | Target chat ID for messages | ā Yes | - |
HOST | Server bind address | No | 127.0.0.1 |
PORT | Server port | No | 8008 |
DEBUG | Enable debug logging | No | false |
# Build image
docker build -t mcp-telegram-server .
# Run container
docker run -d \
--name mcp-telegram-server \
-p 8008:8008 \
--env-file .env \
mcp-telegram-server
# View logs
docker logs -f mcp-telegram-server
# Restart server
docker restart mcp-telegram-server
# Stop server
docker stop mcp-telegram-server
# Remove container
docker rm mcp-telegram-server
# Start services
docker-compose up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose down
# Rebuild and restart
docker-compose up -d --build
| Endpoint | Method | Description |
|---|---|---|
/ | GET | Server info and health check |
/sse | GET | SSE endpoint for MCP clients |
/message | POST | JSON-RPC message endpoint |
Test the server is working:
# Health check
curl http://localhost:8008/
# Expected response:
{
"name": "Telegram MCP Server",
"version": "1.0.0",
"endpoints": {
"sse": "/sse",
"message": "/message"
}
}
# Clone repository
git clone <repository-url>
cd mcp-telegram
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# or
.venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# Configure environment
cp env.example .env
# Edit .env with your credentials
# Run server
python main.py
mcp-telegram/
āāā main.py # Main server application
āāā requirements.txt # Python dependencies
āāā Dockerfile # Docker image definition
āāā docker-compose.yml # Docker Compose configuration
āāā .env # Environment variables (create from env.example)
āāā env.example # Environment template
āāā README.md # This file
.env files to version control0.0.0.0) when containerizedContainer won't start:
# Check logs
docker logs mcp-telegram-server
# Common causes:
# - Missing .env file
# - Invalid bot token
# - Invalid chat ID
MCP client can't connect:
# Verify server is running
curl http://localhost:8008/
# Check SSE endpoint
curl -N -H "Accept: text/event-stream" http://localhost:8008/sse
Messages not sending:
MIT License - see LICENSE file for details.
Content type
Image
Digest
sha256:83a87ece3ā¦
Size
62.5 MB
Last updated
over 1 year ago
docker pull dkasss/mcp-telegram-server