Stig-Johnny/telegram-mcp-server

Telegram MCP Server

A Model Context Protocol (MCP) server that enables Claude Code to send questions and notifications via Telegram.

Features

• Ask Questions: Claude can send questions to you via Telegram when it needs clarification
• Send Notifications: Claude can notify you of important events, task completions, or status updates
• Get Responses: Claude can check for your replies to previous questions

Prerequisites

1. A Telegram bot (create one via @BotFather)
2. Your Telegram chat ID (get it from @userinfobot)
3. Node.js 18+

Installation

1. Clone the repository

git clone https://github.com/Stig-Johnny/telegram-mcp-server.git
cd telegram-mcp-server
npm install

2. Create a secrets file

Create a file at ~/.claude/telegram-secrets.json (or any secure location):

{
  "bot_token": "YOUR_BOT_TOKEN_FROM_BOTFATHER",
  "chat_id": "YOUR_TELEGRAM_CHAT_ID"
}

Security: This file contains secrets and should NOT be committed to git.

3. Configure Claude Code

Add to your ~/.claude/config.json:

{
  "mcpServers": {
    "telegram-notifications": {
      "command": "node",
      "args": ["/path/to/telegram-mcp-server/index.js"],
      "env": {
        "TELEGRAM_CONFIG_FILE": "/Users/yourusername/.claude/telegram-secrets.json"
      }
    }
  }
}

4. Restart Claude Code

The MCP server will be available in your next Claude Code session.

Available Tools

ask_user_telegram

Send a question to the user via Telegram.

Parameters:

• question (required): The question to ask
• context (optional): Additional context about what you're working on

Example:

Claude uses ask_user_telegram with question: "Should I use JWT or session-based authentication?"

notify_user_telegram

Send a notification to the user via Telegram.

Parameters:

• message (required): The notification message
• urgency (optional): "low", "normal", or "high"

Example:

Claude uses notify_user_telegram with message: "Build completed successfully!" urgency: "normal"

get_telegram_response

Check for the user's response to a previous question (text or button click).

Parameters:

• limit (optional): Number of recent messages to check (default: 10)

ask_yes_no_telegram

Ask a yes/no question with clickable buttons.

Parameters:

• question (required): The yes/no question to ask
• context (optional): Additional context about what you're working on

Example:

Claude uses ask_yes_no_telegram with question: "Should I proceed with the refactoring?"

ask_choice_telegram

Ask a multiple choice question with 2-4 clickable buttons.

Parameters:

• question (required): The question to ask
• options (required): Array of 2-4 options
• context (optional): Additional context about what you're working on

Example:

Claude uses ask_choice_telegram with question: "Which database should we use?" options: ["PostgreSQL", "MySQL", "SQLite"]

Alternative Configuration

Instead of a config file, you can use environment variables:

{
  "mcpServers": {
    "telegram-notifications": {
      "command": "node",
      "args": ["/path/to/telegram-mcp-server/index.js"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token",
        "TELEGRAM_CHAT_ID": "your-chat-id"
      }
    }
  }
}

Getting Your Telegram Credentials

Bot Token

1. Open Telegram and search for @BotFather
2. Send /newbot
3. Follow the prompts to name your bot
4. Copy the API token provided

Chat ID

1. Open Telegram and search for @userinfobot
2. Send /start
3. The bot will reply with your user ID - this is your chat ID

Start a conversation with your bot

Before Claude can send you messages, you must start a conversation with your bot:

1. Search for your bot by username in Telegram
2. Send /start or any message to the bot

License

MIT