MCP Telegram Claudecode

MCP电报条款代码

](https://www.npmjs.com/package/mcp-telegram-claudecode) ](https://www.npmjs.com/package/mcp-telegram-claudecode)  ](https://nodejs.org/)

一种MCP（模型上下文协议）服务器，使Claude Code能够通过Telegram发送和接收消息。这允许您通过Telegram应用程序远程与Claude Code交互。

特性

• 从Claude Code向Telegram发送短信
• 用克劳德代码接收来自Telegram的消息
• 将照片/截图发送到Telegram
• 为Telegram被屏蔽的地区提供代理支持
• 新增：通过挂钩进行远程权限审批 -批准/拒绝手机中的敏感操作
• 新增：锁定文件机制 -防止多实例冲突

先决条件

• 18.0.0或更高
• 克劳德代码 安装
• Telegram帐户

快速开始

第一步：创建Telegram Bot

1. 打开Telegram并搜索 @植物学家
2. 发送 /newbot 命令
3. 按照提示命名您的机器人
4. 保存机器人令牌 -它看起来像： 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

第二步：获取您的聊天ID

1. 打开Telegram并搜索 @用户信息机器人
2. 向此机器人发送任何消息
3. 保存 Id 价值 从响应来看，它看起来像： 123456789

第三步：启动你的机器人

重要提示： 在Claude Code收到您的消息之前，您必须与您的机器人开始对话：

1. 通过Telegram中的用户名搜索您的机器人
2. 点击“开始”或向其发送任何消息

步骤4：配置Claude代码

将MCP服务器添加到您的Claude Code配置中。

选项A：使用Claude Code设置命令

claude /settings

然后添加MCP服务器配置。

选项B：直接编辑配置文件

配置文件位于：

• 窗户： %USERPROFILE%\.claude.json
• macOS/Linux： ~/.claude.json

______________________________________________________________________

配置示例

无代理

如果您可以直接访问Telegram：

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

使用代理

如果您需要代理访问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"
      }
    }
  }
}

常见代理端口：

• 冲突： http://127.0.0.1:7890
• V2Ray： http://127.0.0.1:10808
• 影袜： http://127.0.0.1:1080

替换为您的实际代理地址和端口。

______________________________________________________________________

环境变量

______________________________________________________________________

可用工具

配置后，Claude Code将可以访问这些工具：

telegram_send_message

向您的Telegram发送短信。

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

telegram_get_messages

从Telegram检索最近的消息。

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

telegram_check_new

快速检查是否有新消息。

No parameters required

telegram_send_photo

将图像文件发送到Telegram。

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

______________________________________________________________________

用法示例

配置后，您可以要求Claude Code：

• “在Telegram上给我发一条消息，说任务已完成”
• “检查我是否在Telegram上发送了任何新消息”
• “将当前代码的屏幕截图发送到我的Telegram”

______________________________________________________________________

故障排除

“必须配置TELEGRAM_BOT_TOKEN”

确保您已将机器人令牌添加到您的 .claude.json 配置。

“没有新消息”，但您发送了消息

1. 确保你首先与你的机器人开始了对话
2. 检查你的 TELEGRAM_CHAT_ID 是正确的
3. 如果使用代理，请验证代理是否正常工作

连接超时或网络错误

如果您所在的地区Telegram被屏蔽：

1. 确保您的代理软件正在运行
2. 添加 HTTP_PROXY 环境变量到您的配置
3. 验证代理端口是否正确

Bot没有响应

1. 检查bot令牌是否正确（没有额外空格）
2. 确保你已经开始与你的机器人对话
3. 尝试先向您的机器人发送消息，然后检查消息

______________________________________________________________________

远程权限审批（推荐）

而不是使用 --dangerously-skip-permissions，您可以使用Claude Code挂钩通过Telegram远程批准敏感操作。

运作原理

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

1. Claude Code尝试执行敏感操作（编辑、写入、Bash）
2. PreToolUse钩子将详细信息发送到您的电报
3. 你的回复 Y 批准或 N 否认
4. Hook将决定权交还给Claude Code

设置

1. 将钩子复制到您的系统（包含在 hooks/ 目录）
2. 通过以下方式配置Claude代码挂钩 /hooks 命令或编辑设置：

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

1. 设置环境变量（与MCP服务器配置相同）

看 钩子/README.md 有关详细的设置说明。

审批回复

______________________________________________________________________

运作原理

建筑

此MCP服务器充当Claude Code和Telegram之间的桥梁：

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

自动轮询和终端注入（实验）

当MCP服务器启动时，它会自动开始轮询新的Telegram消息。当收到消息时，它会尝试使用以下命令将文本注入活动终端窗口：

1. 剪贴板：消息已复制到系统剪贴板
2. 发送密钥（Windows）：PowerShell脚本模拟Ctrl+V和Enter按键
3. 窗口激活：尝试查找和激活终端窗口（windows终端、cmd、PowerShell、VS代码）

这是一个实验性功能 -它允许通过Telegram对Claude Code进行“远程控制”，但存在可靠性限制。

可用工具

______________________________________________________________________

已知问题和限制

✅ 多个Claude代码实例（在v1.4.0中修复）

问题：如果运行多个Claude Code窗口，每个窗口都将启动自己的MCP服务器实例。

解决方案：锁文件机制现在可以防止多个实例同时轮询。只有第一个实例会轮询；其他人将自动跳过投票。

✅ 注射失败通知（在v1.4.0中修复）

问题：当SendKeys注入失败时，您不会知道。

解决方案：注射失败现在会向Telegram发送通知，以便您知道何时手动检查。

✅ 权限提示（用钩子解决）

问题：无法远程批准敏感操作。

解决方案：使用附带的PreToolUse挂钩通过Telegram进行远程批准。看 远程权限审批 部分。

⚠️ 发送密钥可靠性（Windows）

终端注入功能使用 WriteConsoleInput 无焦点注射API：

它是如何工作的：

• 使用Windows控制台API直接写入控制台输入缓冲区
• 不需要窗口焦点
• 不使用剪贴板
• 当其他应用程序处于活动状态时工作

限制-仅限单终端：

• 当只有一个终端窗口打开时，工作正常
• 如果多个终端打开，消息可能会发送到错误的终端
• 这是由于Windows终端的ConPTY架构

当它可能失败时:

• 多个终端窗口同时打开
• 远程桌面或虚拟机环境
• 屏幕已锁定

变通方案：使用挂钩而不是SendKeys，以获得更可靠的操作，或确保只有一个终端打开。

⚠️ 平台支持

推荐：使用挂钩进行跨平台远程控制。

______________________________________________________________________

更新日志

v1.4.0版本

• ✅ 添加了锁文件机制，以防止多个实例冲突
• ✅ 通过Telegram添加注射失败通知
• ✅ 添加了PreToolUse挂钩用于远程权限审批
• ✅ 添加PostTool使用钩子进行错误通知
• ✅ 使用WriteConsoleInput API改进了终端注入（无需聚焦）
• ✅ 改进了出口清理（信号情报/信号处理）
• ⚠️ 已知限制：仅限单终端模式（多个终端可能会导致注入错误的窗口）

v1.3.0版本

• 添加了照片发送支持
• 添加了代理支持

v1.2.0版本

• 添加了自动轮询和终端注入

v1.1.0版本

• 新增telegram_check_new工具

v1.0.0

• 初始版本

______________________________________________________________________

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

作者

EthanSky

仓库

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