MCP-Telegram-ClaudeCode

An MCP (Model Context Protocol) server that enables Claude Code to send and receive messages via Telegram. This allows you to interact with Claude Code remotely through your Telegram app.

Features

• Send text messages from Claude Code to Telegram
• Receive messages from Telegram in Claude Code
• Send photos/screenshots to Telegram
• Proxy support for regions where Telegram is blocked
• NEW: Remote permission approval via hooks - Approve/deny sensitive operations from your phone
• NEW: Lock file mechanism - Prevents multiple instance conflicts

Prerequisites

• Node.js 18.0.0 or higher
• Claude Code installed
• A Telegram account

Quick Start

Step 1: Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Send /newbot command
3. Follow the prompts to name your bot
4. Save the bot token - it looks like: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

Step 2: Get Your Chat ID

1. Open Telegram and search for @userinfobot
2. Send any message to this bot
3. Save the Id value from the response - it looks like: 123456789

Step 3: Start Your Bot

Important: Before Claude Code can receive your messages, you must start a conversation with your bot:

1. Search for your bot by its username in Telegram
2. Click "Start" or send any message to it

Step 4: Configure Claude Code

Add the MCP server to your Claude Code configuration.

Option A: Using Claude Code settings command

claude /settings

Then add the MCP server configuration.

Option B: Edit configuration file directly

The configuration file is located at:

• Windows: %USERPROFILE%\.claude.json
• macOS/Linux: ~/.claude.json

Configuration Examples

Without Proxy

If you can access Telegram directly:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "mcp-telegram-claudecode"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
        "TELEGRAM_CHAT_ID": "123456789"
      }
    }
  }
}

With Proxy

If you need a proxy to access Telegram:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "mcp-telegram-claudecode"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
        "TELEGRAM_CHAT_ID": "123456789",
        "HTTP_PROXY": "http://127.0.0.1:7890"
      }
    }
  }
}

Common proxy ports:

• Clash: http://127.0.0.1:7890
• V2Ray: http://127.0.0.1:10808
• Shadowsocks: http://127.0.0.1:1080

Replace with your actual proxy address and port.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | TELEGRAM_BOT_TOKEN | Yes | Bot token from @BotFather | | TELEGRAM_CHAT_ID | Yes | Your chat ID from @userinfobot | | HTTP_PROXY | No | HTTP proxy URL (e.g., http://127.0.0.1:7890) | | HTTPS_PROXY | No | HTTPS proxy URL (alternative to HTTP_PROXY) |

Available Tools

Once configured, Claude Code will have access to these tools:

telegram_send_message

Send a text message to your Telegram.

Parameters:
- message (required): The text message to send

telegram_get_messages

Retrieve recent messages from Telegram.

Parameters:
- limit (optional): Maximum number of messages to retrieve (default: 10)

telegram_check_new

Quick check if there are new messages.

No parameters required

telegram_send_photo

Send an image file to Telegram.

Parameters:
- photo_path (required): Absolute path to the image file
- caption (optional): Caption for the photo

Usage Examples

After configuration, you can ask Claude Code to:

• "Send me a message on Telegram saying the task is complete"
• "Check if I sent any new messages on Telegram"
• "Send a screenshot of the current code to my Telegram"

Troubleshooting

"TELEGRAM_BOT_TOKEN must be configured"

Make sure you've added the bot token to your .claude.json configuration.

"No new messages" but you sent messages

1. Make sure you started a conversation with your bot first
2. Check that your TELEGRAM_CHAT_ID is correct
3. If using a proxy, verify the proxy is working

Connection timeout or network error

If you're in a region where Telegram is blocked:

1. Make sure your proxy software is running
2. Add the HTTP_PROXY environment variable to your configuration
3. Verify the proxy port is correct

Bot not responding

1. Check that the bot token is correct (no extra spaces)
2. Make sure you've started a conversation with your bot
3. Try sending a message to your bot first, then check for messages

Remote Permission Approval (Recommended)

Instead of using --dangerously-skip-permissions, you can use Claude Code hooks to approve sensitive operations remotely via Telegram.

How It Works

┌─────────────┐     PreToolUse Hook     ┌─────────────────┐     Telegram API     ┌──────────┐
│ Claude Code │ ──────────────────────► │ Hook Script     │ ◄─────────────────► │ Telegram │
│ (sensitive  │                         │ (asks approval) │                      │ (you)    │
│  operation) │ ◄────────────────────── │                 │                      │          │
└─────────────┘     approve/deny        └─────────────────┘                      └──────────┘

1. Claude Code attempts a sensitive operation (Edit, Write, Bash)
2. PreToolUse hook sends details to your Telegram
3. You reply Y to approve or N to deny
4. Hook returns the decision to Claude Code

Setup

1. Copy the hooks to your system (included in hooks/ directory)
2. Configure Claude Code hooks via /hooks command or edit settings:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          "node /path/to/telegram-claude-mcp/hooks/pretool-approval.js"
        ]
      }
    ]
  }
}

3. Set environment variables (same as MCP server config)

See hooks/README.md for detailed setup instructions.

Approval Responses

| Approve | Deny | |---------|------| | Y, yes, 1, approve | N, no, 0, deny | | 是, 好, 可以 | 否, 不, 拒绝 |

How It Works

Architecture

This MCP server acts as a bridge between Claude Code and Telegram:

┌─────────────┐     MCP Protocol      ┌─────────────────┐     Telegram API     ┌──────────┐
│ Claude Code │ ◄──────────────────► │ MCP Server      │ ◄─────────────────► │ Telegram │
│             │                       │ (this project)  │                      │          │
└─────────────┘                       └─────────────────┘                      └──────────┘

Auto-Polling & Terminal Injection (Experimental)

When the MCP server starts, it automatically begins polling for new Telegram messages. When a message is received, it attempts to inject the text into the active terminal window using:

1. Clipboard: Message is copied to system clipboard
2. SendKeys (Windows): PowerShell script simulates Ctrl+V and Enter keystrokes
3. Window Activation: Attempts to find and activate terminal windows (Windows Terminal, cmd, PowerShell, VS Code)

This is an experimental feature - it enables "remote control" of Claude Code via Telegram, but has reliability limitations.

Tools Available

| Tool | Description | |------|-------------| | telegram_send_message | Send text to Telegram | | telegram_get_messages | Retrieve recent messages | | telegram_check_new | Quick check for new messages | | telegram_send_photo | Send images to Telegram | | telegram_start_polling | Manually start auto-polling | | telegram_stop_polling | Stop auto-polling |

Known Issues & Limitations

✅ Multiple Claude Code Instances (Fixed in v1.4.0)

Problem: If you run multiple Claude Code windows, each will start its own MCP server instance.

Solution: Lock file mechanism now prevents multiple instances from polling simultaneously. Only the first instance will poll; others will skip polling automatically.

✅ Injection Failure Notification (Fixed in v1.4.0)

Problem: When SendKeys injection fails, you wouldn't know about it.

Solution: Failed injections now send a notification to Telegram, so you know when to check manually.

✅ Permission Prompts (Solved with Hooks)

Problem: Cannot approve sensitive operations remotely.

Solution: Use the included PreToolUse hooks for remote approval via Telegram. See Remote Permission Approval section.

⚠️ SendKeys Reliability (Windows)

The terminal injection feature uses WriteConsoleInput API for no-focus injection:

How it works:

• Uses Windows Console API to write directly to the console input buffer
• Does not require window focus
• Does not use clipboard
• Works when other applications are active

Limitation - Single Terminal Only:

• Works correctly when only one terminal window is open
• If multiple terminals are open, messages may go to the wrong terminal
• This is due to Windows Terminal's ConPTY architecture

When it may fail:

• Multiple terminal windows open simultaneously
• Remote desktop or virtual machine environments
• Screen is locked

Workaround: Use hooks instead of SendKeys for more reliable operation, or ensure only one terminal is open.

⚠️ Platform Support

| Platform | MCP Tools | Auto-Injection | Hooks | |----------|-----------|----------------|-------| | Windows | ✅ Full | ✅ SendKeys | ✅ Full | | macOS | ✅ Full | ❌ Not implemented | ✅ Full | | Linux | ✅ Full | ❌ Not implemented | ✅ Full |

Recommendation: Use hooks for cross-platform remote control.

Changelog

v1.4.0

• ✅ Added lock file mechanism to prevent multiple instance conflicts
• ✅ Added injection failure notifications via Telegram
• ✅ Added PreToolUse hook for remote permission approval
• ✅ Added PostToolUse hook for error notifications
• ✅ Improved terminal injection with WriteConsoleInput API (no focus required)
• ✅ Improved exit cleanup (SIGINT/SIGTERM handling)
• ⚠️ Known limitation: Single terminal mode only (multiple terminals may cause injection to wrong window)

v1.3.0

• Added photo sending support
• Added proxy support

v1.2.0

• Added auto-polling and terminal injection

v1.1.0

• Added telegram_check_new tool

v1.0.0

• Initial release

License

MIT License - see LICENSE file for details.

Author

EthanSky

Repository

https://github.com/EthanSky2986/mcp-telegram-claudecode