Skip to content
BranchesTags
 
 

Repository files navigation

MCP-Telegram-ClaudeCode

npm version npm downloads License: MIT Node.js Version

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
  • NEW: Hammerspoon injection (macOS) - More reliable terminal injection via CGEvent API
  • NEW: Auto webhook cleanup - Ensures message receiving works even if a webhook was previously set

Prerequisites

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
  4. Check stderr logs for "Webhook cleared" message - if a webhook was previously set, getUpdates silently returns empty results (v1.6.0 fixes this automatically)

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"
        ]
      }
    ]
  }
}
  1. 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 ✅ Hammerspoon / ⚠️ AppleScript fallback ✅ Full
Linux ✅ Full ❌ Not implemented ✅ Full

macOS Auto-Injection: Requires Hammerspoon with the CLI tool enabled:

  1. Install Hammerspoon: brew install --cask hammerspoon
  2. Open Hammerspoon preferences
  3. Enable "Enable CLI tool (hs)" in the preferences
  4. The hs command should now be available in your terminal

If Hammerspoon is not installed, falls back to AppleScript (clipboard + paste), which is less reliable and requires window focus.

Recommendation: Use hooks for cross-platform remote control, or Hammerspoon on macOS for auto-injection.

Changelog

v1.6.0

  • ✅ Fixed message receiving: auto-delete webhook on startup (getUpdates returns empty if webhook is set)
  • ✅ Added getMe diagnostic on startup to validate bot token
  • ✅ Added axios timeouts to polling/check requests to prevent hanging
  • ✅ Added Hammerspoon injection for macOS (more reliable than AppleScript)
  • ✅ AppleScript fallback when Hammerspoon is not installed

v1.5.0

  • ✅ Added video and document sending support
  • ✅ Improved terminal injection security

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

About

MCP server for Telegram integration with Claude Code

Resources

Readme
License
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages