# Telegram MCP Server

一个基于 Model Context Protocol (MCP) 的 Telegram Bot API 服务器，让 Claude 能够通过 Telegram Bot 发送消息、图片、视频等。

## 功能

- **发送文本消息** - 向用户、群组或频道发送文本消息
- **发送图片** - 发送图片消息（支持 file_id、URL）
- **发送视频** - 发送视频消息（支持 file_id、URL）
- **编辑消息** - 编辑已发送的文本消息
- **删除消息** - 删除已发送的消息
- **获取 Bot 信息** - 获取当前 Bot 的基本信息
- **获取消息更新** - 获取 Bot 收到的最新消息，用于获取 chat_id

## 安装

### 方式一：使用 npx（推荐）

无需安装，直接在 Claude Desktop 配置中使用 npx 运行。

### 方式二：全局安装

```bash
npm install -g telegram-mcp
```

### 方式三：从源码安装

```bash
git clone https://github.com/chenqwwq/telegram-mcp.git
cd telegram-mcp
npm install
```

## 配置

### 1. 创建 Telegram Bot

1. 在 Telegram 中搜索 [@BotFather](https://t.me/BotFather)
2. 发送 `/newbot` 命令创建新 Bot
3. 按提示设置 Bot 名称
4. 保存 BotFather 返回的 **Token**（格式：`123456789:ABCdefGHIjklMNOpqrsTUVwxyz`）

### 2. 获取 Chat ID

1. 向你的 Bot 发送一条消息
2. 访问 `https://api.telegram.org/bot<你的TOKEN>/getUpdates`
3. 在返回的 JSON 中找到 `chat.id` 字段

### 3. 配置 Claude Desktop

编辑 Claude Desktop 配置文件：

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

添加以下配置：

```json
{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "telegram-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "你的_BOT_TOKEN"
      }
    }
  }
}
```

如果使用代理：

```json
{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "telegram-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "你的_BOT_TOKEN",
        "HTTPS_PROXY": "http://127.0.0.1:7890"
      }
    }
  }
}
```

## 可用工具

### 1. send_telegram_message

发送文本消息到指定的聊天。

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| chat_id | string | 是 | 目标聊天 ID |
| text | string | 是 | 消息内容 |
| parse_mode | string | 否 | 解析模式：HTML、Markdown、MarkdownV2 |

### 2. send_photo

发送图片到指定的聊天。

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| chat_id | string | 是 | 目标聊天 ID |
| photo | string | 是 | 图片（file_id 或 URL） |
| caption | string | 否 | 图片说明（最多 1024 字符） |
| parse_mode | string | 否 | 说明文字解析模式 |

### 3. send_video

发送视频到指定的聊天。

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| chat_id | string | 是 | 目标聊天 ID |
| video | string | 是 | 视频（file_id 或 URL） |
| duration | number | 否 | 视频时长（秒） |
| width | number | 否 | 视频宽度 |
| height | number | 否 | 视频高度 |
| thumbnail | string | 否 | 缩略图 |
| caption | string | 否 | 视频说明 |
| parse_mode | string | 否 | 说明文字解析模式 |

### 4. edit_message_text

编辑已发送的文本消息。

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| chat_id | string | 否* | 目标聊天 ID |
| message_id | number | 否* | 消息 ID |
| text | string | 是 | 新的消息文本 |
| parse_mode | string | 否 | 解析模式 |
| inline_message_id | string | 否* | 内联消息 ID |

*注：需要 `chat_id` + `message_id` 或 `inline_message_id` 其中一组

### 5. delete_message

删除已发送的消息。

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| chat_id | string | 是 | 目标聊天 ID |
| message_id | number | 是 | 消息 ID |

### 6. get_me

获取 Bot 的基本信息。

### 7. get_updates

获取 Bot 收到的最新消息更新。

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| limit | number | 否 | 获取数量限制（默认 10） |

## 使用示例

在 Claude 中，你可以这样使用：

```
请用 Telegram 给 chat_id 123456789 发送一条消息："你好，这是测试消息"

请用 Telegram 发送一张图片到 chat_id 123456789，图片 URL 是 https://example.com/photo.jpg

请编辑 chat_id 123456789 中 message_id 为 42 的消息，新内容是 "已更新"

请删除 chat_id 123456789 中 message_id 为 42 的消息
```

## 环境变量

| 变量名 | 描述 | 必填 |
|--------|------|------|
| TELEGRAM_BOT_TOKEN | Telegram Bot Token | 是 |
| HTTPS_PROXY / HTTP_PROXY | 代理地址 | 否 |
| TELEGRAM_PROXY | Telegram 专用代理地址 | 否 |

## 注意事项

1. **消息删除限制**：Bot 只能删除 48 小时内发送的消息（部分情况例外）
2. **图片大小限制**：通过 URL 发送的图片最大 5MB
3. **视频大小限制**：通过 URL 发送的视频最大 20MB
4. **Bot 隐私模式**：默认情况下 Bot 只能接收以 `/` 开头的命令或 @提及，如需接收所有消息请在 BotFather 中关闭隐私模式

## 开发

```bash
# 克隆仓库
git clone https://github.com/chenqwwq/telegram-mcp.git
cd telegram-mcp

# 安装依赖
npm install

# 运行
npm start
```

## 许可证

MIT License

## 相关链接

- [Telegram Bot API 文档](https://core.telegram.org/bots/api)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/)