mcp-telegram-claudecode 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 EthanSky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# 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
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 18.0.0 or higher
+- [Claude Code](https://claude.ai/code) installed
+- A Telegram account
+
+## Quick Start
+
+### Step 1: Create a Telegram Bot
+
+1. Open Telegram and search for [@BotFather](https://t.me/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](https://t.me/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**
+```bash
+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 (US, Europe, etc.)
+
+If you can access Telegram directly without a proxy:
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "npx",
+      "args": ["-y", "mcp-telegram-claudecode"],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
+        "TELEGRAM_CHAT_ID": "123456789"
+      }
+    }
+  }
+}
+```
+
+### With Proxy (China, Iran, Russia, etc.)
+
+If Telegram is blocked in your region, you need to configure a proxy:
+
+```json
+{
+  "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
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Author
+
+EthanSky
+
+## Repository
+
+https://github.com/EthanSky2986/mcp-telegram-claudecode

package/README_CN.md

@@ -0,0 +1,195 @@
+# MCP-Telegram-ClaudeCode
+
+一个 MCP（Model Context Protocol）服务器，让 Claude Code 能够通过 Telegram 发送和接收消息。这样你就可以通过 Telegram 远程与 Claude Code 交互。
+
+## 功能特性
+
+- 从 Claude Code 发送文字消息到 Telegram
+- 在 Claude Code 中接收 Telegram 消息
+- 发送图片/截图到 Telegram
+- 支持代理（适用于无法直接访问 Telegram 的地区）
+
+## 前置要求
+
+- [Node.js](https://nodejs.org/) 18.0.0 或更高版本
+- 已安装 [Claude Code](https://claude.ai/code)
+- 一个 Telegram 账号
+
+## 快速开始
+
+### 第一步：创建 Telegram 机器人
+
+1. 打开 Telegram，搜索 [@BotFather](https://t.me/BotFather)
+2. 发送 `/newbot` 命令
+3. 按照提示为你的机器人起名
+4. **保存机器人 Token** - 格式类似：`1234567890:ABCdefGHIjklMNOpqrsTUVwxyz`
+
+### 第二步：获取你的 Chat ID
+
+1. 打开 Telegram，搜索 [@userinfobot](https://t.me/userinfobot)
+2. 给这个机器人发送任意消息
+3. **保存返回的 `Id` 值** - 格式类似：`123456789`
+
+### 第三步：启动你的机器人
+
+**重要：** 在 Claude Code 能接收你的消息之前，你必须先和你的机器人开始对话：
+1. 在 Telegram 中搜索你的机器人用户名
+2. 点击"开始"或发送任意消息
+
+### 第四步：配置 Claude Code
+
+将 MCP 服务器添加到你的 Claude Code 配置中。
+
+**方式 A：使用 Claude Code 设置命令**
+```bash
+claude /settings
+```
+然后添加 MCP 服务器配置。
+
+**方式 B：直接编辑配置文件**
+
+配置文件位置：
+- Windows: `%USERPROFILE%\.claude.json`
+- macOS/Linux: `~/.claude.json`
+
+---
+
+## 配置示例
+
+### 不使用代理（美国、欧洲等地区）
+
+如果你可以直接访问 Telegram：
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "npx",
+      "args": ["-y", "mcp-telegram-claudecode"],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
+        "TELEGRAM_CHAT_ID": "123456789"
+      }
+    }
+  }
+}
+```
+
+### 使用代理（中国、伊朗、俄罗斯等地区）
+
+如果你所在的地区无法直接访问 Telegram，需要配置代理：
+
+```json
+{
+  "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"
+      }
+    }
+  }
+}
+```
+
+**常用代理端口：**
+- Clash: `http://127.0.0.1:7890`
+- V2Ray: `http://127.0.0.1:10808`
+- Shadowsocks: `http://127.0.0.1:1080`
+
+请替换为你实际的代理地址和端口。
+
+---
+
+## 环境变量
+
+| 变量名 | 是否必需 | 说明 |
+|--------|----------|------|
+| `TELEGRAM_BOT_TOKEN` | 是 | 从 @BotFather 获取的机器人 Token |
+| `TELEGRAM_CHAT_ID` | 是 | 从 @userinfobot 获取的 Chat ID |
+| `HTTP_PROXY` | 否 | HTTP 代理地址（如 `http://127.0.0.1:7890`） |
+| `HTTPS_PROXY` | 否 | HTTPS 代理地址（HTTP_PROXY 的替代选项） |
+
+---
+
+## 可用工具
+
+配置完成后，Claude Code 将可以使用以下工具：
+
+### telegram_send_message
+发送文字消息到你的 Telegram。
+```
+参数：
+- message（必需）：要发送的文字消息
+```
+
+### telegram_get_messages
+获取 Telegram 的最近消息。
+```
+参数：
+- limit（可选）：获取消息的最大数量（默认：10）
+```
+
+### telegram_check_new
+快速检查是否有新消息。
+```
+无需参数
+```
+
+### telegram_send_photo
+发送图片文件到 Telegram。
+```
+参数：
+- photo_path（必需）：图片文件的绝对路径
+- caption（可选）：图片说明文字
+```
+
+---
+
+## 使用示例
+
+配置完成后，你可以让 Claude Code：
+
+- "在 Telegram 上给我发消息说任务完成了"
+- "检查一下我在 Telegram 上有没有发新消息"
+- "把当前代码的截图发到我的 Telegram"
+
+---
+
+## 常见问题
+
+### "TELEGRAM_BOT_TOKEN must be configured"
+确保你已经在 `.claude.json` 配置文件中添加了机器人 Token。
+
+### 发了消息但显示"No new messages"
+1. 确保你已经先和机器人开始了对话
+2. 检查 `TELEGRAM_CHAT_ID` 是否正确
+3. 如果使用代理，确认代理正常工作
+
+### 连接超时或网络错误
+如果你在无法直接访问 Telegram 的地区：
+1. 确保代理软件正在运行
+2. 在配置中添加 `HTTP_PROXY` 环境变量
+3. 确认代理端口正确
+
+### 机器人没有响应
+1. 检查机器人 Token 是否正确（没有多余空格）
+2. 确保你已经和机器人开始了对话
+3. 先给机器人发一条消息，然后再检查消息
+
+---
+
+## 许可证
+
+MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。
+
+## 作者
+
+EthanSky
+
+## 仓库地址
+
+https://github.com/EthanSky2986/mcp-telegram-claudecode

package/index.js

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+
+/**
+ * Telegram Claude MCP Server
+ * MCP server for Telegram integration with Claude Code
+ */
+
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} = require('@modelcontextprotocol/sdk/types.js');
+const axios = require('axios');
+const { HttpsProxyAgent } = require('https-proxy-agent');
+
+// Configuration from environment variables
+const BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN;
+const CHAT_ID = process.env.TELEGRAM_CHAT_ID;
+const PROXY_URL = process.env.HTTP_PROXY || process.env.HTTPS_PROXY;
+
+// Setup axios with proxy if configured
+let axiosInstance = axios;
+if (PROXY_URL) {
+  const agent = new HttpsProxyAgent(PROXY_URL);
+  axiosInstance = axios.create({
+    httpsAgent: agent,
+    proxy: false
+  });
+}
+
+const API_BASE = `https://api.telegram.org/bot${BOT_TOKEN}`;
+
+// Track last update ID for polling
+let lastUpdateId = 0;
+
+/**
+ * Send a text message to Telegram
+ */
+async function sendMessage(text) {
+  if (!BOT_TOKEN || !CHAT_ID) {
+    throw new Error('TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID must be configured');
+  }
+
+  const response = await axiosInstance.post(`${API_BASE}/sendMessage`, {
+    chat_id: CHAT_ID,
+    text: text,
+    parse_mode: 'Markdown'
+  });
+
+  return response.data;
+}
+
+/**
+ * Send a photo to Telegram
+ */
+async function sendPhoto(photoPath, caption = '') {
+  if (!BOT_TOKEN || !CHAT_ID) {
+    throw new Error('TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID must be configured');
+  }
+
+  const fs = require('fs');
+  const FormData = require('form-data');
+
+  const form = new FormData();
+  form.append('chat_id', CHAT_ID);
+  form.append('photo', fs.createReadStream(photoPath));
+  if (caption) {
+    form.append('caption', caption);
+  }
+
+  const response = await axiosInstance.post(`${API_BASE}/sendPhoto`, form, {
+    headers: form.getHeaders()
+  });
+
+  return response.data;
+}
+
+/**
+ * Get new messages from Telegram
+ */
+async function getMessages(limit = 10) {
+  if (!BOT_TOKEN) {
+    throw new Error('TELEGRAM_BOT_TOKEN must be configured');
+  }
+
+  const response = await axiosInstance.get(`${API_BASE}/getUpdates`, {
+    params: {
+      offset: lastUpdateId + 1,
+      limit: limit,
+      timeout: 0
+    }
+  });
+
+  const messages = [];
+  if (response.data.ok && response.data.result.length > 0) {
+    for (const update of response.data.result) {
+      lastUpdateId = update.update_id;
+      if (update.message && update.message.text) {
+        // Filter by chat ID if configured
+        if (!CHAT_ID || update.message.chat.id.toString() === CHAT_ID) {
+          messages.push({
+            id: update.message.message_id,
+            from: update.message.from.first_name || update.message.from.username,
+            text: update.message.text,
+            date: new Date(update.message.date * 1000).toISOString()
+          });
+        }
+      }
+    }
+  }
+
+  return messages;
+}
+
+/**
+ * Check for new messages (non-blocking)
+ */
+async function checkNewMessages() {
+  if (!BOT_TOKEN) {
+    throw new Error('TELEGRAM_BOT_TOKEN must be configured');
+  }
+
+  const response = await axiosInstance.get(`${API_BASE}/getUpdates`, {
+    params: {
+      offset: lastUpdateId + 1,
+      limit: 100,
+      timeout: 0
+    }
+  });
+
+  let hasNew = false;
+  let latestMessage = null;
+
+  if (response.data.ok && response.data.result.length > 0) {
+    for (const update of response.data.result) {
+      lastUpdateId = update.update_id;
+      if (update.message && update.message.text) {
+        if (!CHAT_ID || update.message.chat.id.toString() === CHAT_ID) {
+          hasNew = true;
+          latestMessage = {
+            from: update.message.from.first_name || update.message.from.username,
+            text: update.message.text
+          };
+        }
+      }
+    }
+  }
+
+  return { hasNew, latestMessage, updateId: lastUpdateId };
+}
+
+// Create MCP server
+const server = new Server(
+  {
+    name: 'telegram-claude-mcp',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Define available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'telegram_send_message',
+        description: 'Send a text message to the configured Telegram chat. Use this to communicate with the user via Telegram.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            message: {
+              type: 'string',
+              description: 'The message text to send'
+            }
+          },
+          required: ['message']
+        }
+      },
+      {
+        name: 'telegram_get_messages',
+        description: 'Get recent messages from Telegram. Use this to check for new messages from the user.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            limit: {
+              type: 'number',
+              description: 'Maximum number of messages to retrieve (default: 10)'
+            }
+          }
+        }
+      },
+      {
+        name: 'telegram_check_new',
+        description: 'Quick check if there are new messages from Telegram without retrieving all of them.',
+        inputSchema: {
+          type: 'object',
+          properties: {}
+        }
+      },
+      {
+        name: 'telegram_send_photo',
+        description: 'Send a photo/image to the configured Telegram chat.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            photo_path: {
+              type: 'string',
+              description: 'Absolute path to the image file'
+            },
+            caption: {
+              type: 'string',
+              description: 'Optional caption for the photo'
+            }
+          },
+          required: ['photo_path']
+        }
+      }
+    ]
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'telegram_send_message': {
+        const result = await sendMessage(args.message);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Message sent successfully. Message ID: ${result.result.message_id}`
+            }
+          ]
+        };
+      }
+
+      case 'telegram_get_messages': {
+        const messages = await getMessages(args.limit || 10);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: messages.length > 0
+                ? JSON.stringify(messages, null, 2)
+                : 'No new messages'
+            }
+          ]
+        };
+      }
+
+      case 'telegram_check_new': {
+        const result = await checkNewMessages();
+        return {
+          content: [
+            {
+              type: 'text',
+              text: result.hasNew
+                ? `New message from ${result.latestMessage.from}: ${result.latestMessage.text}`
+                : 'No new messages'
+            }
+          ]
+        };
+      }
+
+      case 'telegram_send_photo': {
+        const result = await sendPhoto(args.photo_path, args.caption || '');
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Photo sent successfully. Message ID: ${result.result.message_id}`
+            }
+          ]
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error: ${error.message}`
+        }
+      ],
+      isError: true
+    };
+  }
+});
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('Telegram Claude MCP server running');
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "mcp-telegram-claudecode",
+  "version": "1.0.0",
+  "description": "MCP server for Telegram integration with Claude Code - Send and receive messages via Telegram",
+  "main": "index.js",
+  "bin": {
+    "mcp-telegram-claudecode": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "telegram",
+    "claude",
+    "claude-code",
+    "remote-control",
+    "bot",
+    "anthropic"
+  ],
+  "author": "EthanSky",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "axios": "^1.6.0",
+    "https-proxy-agent": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/EthanSky2986/mcp-telegram-claudecode"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "strict": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "outDir": "./dist"
+  },
+  "include": ["*.js"],
+  "exclude": ["node_modules"]
+}