Telegram MCP Server for Claude Code

A bidirectional Telegram bridge that allows Claude Code to communicate with you via Telegram. Built on the Model Context Protocol (MCP).

Features

• Send messages from Claude Code to your Telegram
• Receive instructions — send Telegram messages that Claude Code can read
• Task tracking — create, update, and monitor tasks with Telegram notifications
• Persistent storage — all messages and tasks stored in SQLite
• Webhook-based — no polling, instant message delivery

Architecture

You (Telegram) ←→ Telegram Bot API ←→ Webhook Server (Express, port 3100) ←→ SQLite DB
                                                                                ↕
Claude Code ←→ MCP Server (stdio) ←→ SQLite DB

Two processes share the same SQLite database:

• Webhook Server — receives your Telegram messages via bot webhook
• MCP Server — spawned by Claude Code via stdio, reads/writes the same DB

Prerequisites

• Node.js 18+
• A Telegram bot (create one via @BotFather)
• Your Telegram chat ID (use @userinfobot to find it)
• A publicly accessible URL for the webhook (e.g., via reverse proxy or tunnel)

Installation

git clone https://github.com/xmart2k/telegram-mcp.git
cd telegram-mcp
npm install
npm run build

Configuration

Copy the example environment file and fill in your values:

cp .env.example .env

Edit .env:

TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
TELEGRAM_CHAT_ID=your_telegram_chat_id
WEBHOOK_PORT=3100
WEBHOOK_HOST=0.0.0.0
DB_PATH=/path/to/data/telegram-mcp.db

Claude Code Setup

Add the MCP server to your Claude Code configuration (.mcp.json in your project or ~/.claude/settings.json globally):

{
  "mcpServers": {
    "telegram-pm": {
      "command": "node",
      "args": ["/path/to/telegram-mcp/dist/mcp-server.js"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token",
        "TELEGRAM_CHAT_ID": "your_chat_id",
        "DB_PATH": "/path/to/telegram-mcp/data/telegram-mcp.db"
      }
    }
  }
}

Running the Webhook Server

Start the webhook server to receive Telegram messages:

# Development
npm run dev:webhook

# Production
npm run start:webhook

Systemd Service (optional)

For production, install as a systemd service:

# Edit telegram-webhook.service to match your paths
sudo cp telegram-webhook.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now telegram-webhook

Register the Webhook

After the server is running and accessible via a public URL, register the webhook with Telegram (one-time setup):

curl -X POST http://localhost:3100/webhook/setup \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-domain.com/webhook"}'

Verify webhook status:

curl http://localhost:3100/webhook/info

MCP Tools

Tool	Description
send_message	Send a Telegram message to you
get_instructions	Check for pending messages from you
acknowledge_instruction	Mark a specific instruction as processed
acknowledge_all_instructions	Mark all pending instructions as processed
create_task	Create a tracked task with optional notification
update_task_status	Update task status with optional notification
get_task_status	Get status and history of a task
list_active_tasks	List all non-completed tasks
list_all_tasks	List all tasks including completed

Usage Examples

Once configured, Claude Code can use the tools naturally:

• "Send me a message on Telegram saying the deploy is done" — uses send_message
• "Check if I sent any instructions" — uses get_instructions
• "Create a task BUG-42 to fix the login issue" — uses create_task
• "Mark BUG-42 as completed" — uses update_task_status

You can also send messages from Telegram to Claude Code — they'll be queued and available via get_instructions.

API Endpoints (Webhook Server)

Method	Path	Description
POST	/webhook	Telegram bot updates (configured automatically)
POST	/webhook/setup	Register webhook URL with Telegram
GET	/webhook/info	Current webhook status
GET	/health	Health check

License

MIT