电报机器人MCP服务器
一种MCP(模型上下文协议)服务器,用于通过Telegram Bot API发送丰富格式的消息。
支持两者 超文本标记语言 和 MarkdownV2 具有完整Telegram实体覆盖的输出模式。
主要特点
- 双解析模式:从中选择
HTML(默认,推荐)和MarkdownV2输出 - 完整的Telegram实体支持:粗体、斜体、下划线、删除线、扰流板、黑引号、代码、链接等
- 嵌套格式:
**bold _italic_ bold**通过基于令牌的解析器正确呈现 - 智能自动拆分:超过4096个字符的邮件将自动按自然边界拆分
- 自动回退:转换或发送失败时回退到纯文本
- MCP协议:适用于Claude Desktop、Claude Code、VS Code Copilot、Cursor、Windsurf等
- 内联键盘:带有URL、callback_data等的按钮。
- 照片发送:发送带有格式化字幕的照片
- 结构化日志记录:具有可配置保留期的JSON格式日志
安装```bash
npm install -g telegram-chat-bot-mcp
### 更新```bash
npm update -g telegram-chat-bot-mcp
电报机器人设置
1) 通过@BotFather创建机器人
- 搜索 @植物学家 在Telegram中
- 发送
/newbot并遵循指示 - 设置机器人名称和用户名(用户名必须以结尾
bot) - 保存Bot令牌(格式:
:)
2) 获取聊天ID
- 使用@userinfobot或@getidsbot:启动机器人以查看您的用户ID
- 对于团体:将机器人添加到组中,发送测试消息,然后调用:```
https://api.telegram.org/bot/getUpdates
找到 `chat.id` 值(组ID为负。, `-1001234567890`)
## MCP客户端配置
此MCP服务器集成了各种AI编码工具。请在下面选择您的工具:
### 克劳德桌面版
**配置文件:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **视窗**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
**访问权限:** Claude>设置>开发人员>编辑配置
**例子:**```json
{
"mcpServers": {
"telegram": {
"command": "telegram-chat-bot-mcp",
"env": {
"TELEGRAM_BOT_TOKEN": "",
"TELEGRAM_CHAT_ID": ""
}
}
}
}
克劳德代码(CLI)
配置文件(按优先级):
- 项目 (团队分享):
.mcp.json(项目根) - 用户 (全球):
~/.config/claude-code/mcp.json
通过命令添加服务器:```bash
nano ~/.config/claude-code/mcp.json
After changes, reconnect
claude mcp reconnect telegram
**例子:**```json
{
"mcpServers": {
"telegram": {
"command": "telegram-chat-bot-mcp",
"env": {
"TELEGRAM_BOT_TOKEN": "",
"TELEGRAM_CHAT_ID": ""
}
}
}
}
VS代码(GitHub副本)
要求: VS代码1.99+(2025年3月),启用代理模式
配置文件:
- 工作区:
.vscode/mcp.json(项目特定) - 用户:命令面板>“MCP:打开用户配置”
示例(.vcode/mcp.json):```json
{
"servers": {
"telegram": {
"type": "stdio",
"command": "telegram-chat-bot-mcp",
"env": {
"TELEGRAM_BOT_TOKEN": "",
"TELEGRAM_CHAT_ID": ""
}
}
}
}
### Cursor IDE
**配置文件:**
- **全球**: `~/.cursor/mcp.json`
- **项目**: `.cursor/mcp.json`
**访问权限:** 设置>MCP或直接文件编辑
**例子:**```json
{
"mcpServers": {
"telegram": {
"command": "telegram-chat-bot-mcp",
"env": {
"TELEGRAM_BOT_TOKEN": "",
"TELEGRAM_CHAT_ID": ""
}
}
}
}
Windsurf IDE(Codeium)
配置文件:
- macOS:
~/.codeium/windsurf/mcp_config.json - 视窗:
%USERPROFILE%\.codeium\windsurf\mcp_config.json
访问权限: 级联工具栏>锤子图标>配置
例子:```json
{
"mcpServers": {
"telegram": {
"command": "telegram-chat-bot-mcp",
"env": {
"TELEGRAM_BOT_TOKEN": "",
"TELEGRAM_CHAT_ID": ""
}
}
}
}
## 提供的工具(6)
|工具|说明|
|------|-------------|
| **`send_telegram_text`** |发送纯文本消息|
| **`send_telegram_markdown`** |转换Markdown并通过HTML或MarkdownV2发送(推荐)|
| **`send_telegram_with_buttons`** |使用内联键盘按钮发送消息|
| **`send_telegram_photo`** |发送图片/照片(URL或Telegram file_id)|
| **`markdown_to_telegram_html`** |将Markdown转换为Telegram HTML(实用程序)|
| **`convert_markdown`** |将Markdown转换为HTML或MarkdownV2格式(实用程序)|
所有工具使用 `TELEGRAM_CHAT_ID` 默认情况下,环境变量。您可以选择用个人覆盖 `chatId` 参数。
### 解析模式选择
这 `send_telegram_markdown` 和 `convert_markdown` 工具接受a `parseMode` 参数:
|模式|描述|何时使用|
|------|-------------|-------------|
| `HTML` (默认)|将Markdown转换为Telegram HTML |建议用于大多数用例。更容易逃脱(3个字符)。 |
| `MarkdownV2` |将Markdown转换为Telegram MarkdownV2|需要本机MarkdownV2输出时。更严格的转义(18个字符)。 |
**示例——使用MarkdownV2发送:**```json
{
"tool": "send_telegram_markdown",
"arguments": {
"markdown": "**Bold** and __underline__ text",
"parseMode": "MarkdownV2"
}
}
支持的Markdown语法
语法 · 输入 · HTML输出 · MarkdownV2输出
大胆 · **bold** · bold · *bold*
意大利语 · *italic* · italic · _italic_
下划线 · __underline__ · underline · __underline__
罢工 · ~~strike~~ · strike · ~strike~
剧透 · \ · \ · spoiler\ · \ · · spoiler · \ · \ · spoiler\ · \ ·
内联代码 · `code` · code · `code`
代码块```lang\ncode\n``` | `
code
|```` ```lang\ncode\n``` ```` |
Blockquote ·> quote·
quote
·>quote链接 ·text·text·text图片 · `` · 带有表情符号前缀的链接 · ``
头球# H1,## H2· 粗体标题 · 粗体文本
列表 ·- item· 要点 · 逃逸列表
表格 ·\ · A \ · B \ · ·
单空间|```` ``````` 单空间|
|嵌套|bold italic|bold italic|bold italic` |
转义
逃逸由转换器自动处理:
- HTML模式:逃脱
&,<,>(3个字符) - MarkdownV2模式:逃脱
_ * [ ] ( ) ~ \> # + - = | { } .!`(18个字符) - 内部代码块:最小逃逸(仅
`和\MarkdownV2) - 内部URL:只有
)和\MarkdownV2
环境变量
必需
| 变量 | 描述 |
|---|---|
TELEGRAM_BOT_TOKEN |
来自@BotFather的机器人令牌 |
TELEGRAM_CHAT_ID |
目标聊天ID(用户或组) |
可选(日志记录)
| 变量 | 描述 | 默认值 |
|---|---|---|
LOG_LEVEL |
日志级别(调试、信息、警告、错误) | INFO |
LOG_DIR |
日志目录路径 | ./logs |
LOG_RETENTION_DAYS |
保留日志的天数 | 30 |
LOG_ENABLE_CONSOLE |
启用控制台输出 | true |
测试
# Set environment variables
export TELEGRAM_BOT_TOKEN=""
export TELEGRAM_CHAT_ID=""
# Build first
npm run build
# Unit tests (154 tests)
npx vitest run
# Individual test scripts
npm run test:telegram:text # Plain text test
npm run test:telegram:markdown # Markdown conversion test
npm run test:mcp:server # MCP protocol test```
## 发展
```bash
npm install # Install dependencies
npm run build # Build TypeScript
npm run dev # Run in dev mode
npm run lint # Lint code
npm run lint:fix # Auto-fix lint issues
npx vitest run # Run all tests```
## 建筑
src/
├── server.ts # MCP server & tool registration
├── tools/
│ ├── markdownToTelegram.ts # Markdown → Telegram HTML (token-based parser)
│ ├── markdownToMarkdownV2.ts # Markdown → Telegram MarkdownV2
│ ├── markdownConverter.ts # Dual-mode router (HTML / MarkdownV2)
│ ├── sendTelegramMarkdown.ts # Send with auto-conversion & splitting
│ ├── sendTelegramText.ts # Send plain text
│ ├── sendTelegramWithButtons.ts # Send with inline keyboard
│ └── sendTelegramPhoto.ts # Send photos
├── utils/
│ ├── escapeUtils.ts # HTML & MarkdownV2 escape functions
│ ├── markdownSplitter.ts # Auto-split long messages
│ ├── axiosConfig.ts # HTTP client config
│ └── logger.ts # Structured JSON logger
└── types/
└── telegram.ts # Telegram API type definitions```
限制和注意事项
Telegram Bot API约束
- HTML标记:支持
b,i,u,s,code,pre,a,blockquote,tg-spoiler - 表格:渲染为 `
等宽文本(Telegram不支持
`)
- 图像:仅HTTPS,~10MB文件大小限制
- 消息长度:4096个字符限制(超过时自动拆分)
- MarkdownV2逃逸:必须转义所有18个特殊字符(自动处理)
HTML与MarkdownV2的比较
| 特性 | HTML | MarkdownV2 |
|---|---|---|
| 转义字符 | 3(<, >, &) |
18 (_, *, [, ]等等) |
| 错误风险 | 低 | 高(一次漏报=400个错误) |
| 嵌套格式 | 清除XML样式标记 | 基于符号,可能存在歧义 |
| 建议 | 默认选择 | 需要本机V2输出时 |
安全
Bot Token和聊天ID是敏感信息。
- 永远不要将凭据提交到Git
- 不要在公共存储库中公开
- 使用环境变量作为机密
- 如果泄露,通过@BotFather重新生成令牌
故障排除
MCP服务器未连接:
- 验证全局安装:
npm install -g telegram-chat-bot-mcp - 检查环境变量是否设置正确
- 配置更改后重新启动AI工具
超时错误(WSL用户):
- 此包包括IPv4强制,以防止WSL IPv6超时问题
- 如果超时仍然存在,请检查api.telegram.org的网络连接
工具未出现:
- 验证配置文件是否位于工具的正确位置
- 验证JSON语法
- 重新启动MCP服务器或重新连接
MarkdownV2发送失败(400错误请求):
- 这通常意味着一个没有伪装的特殊角色
- 切换到更宽容的HTML模式(默认)
- 查看Telegram Bot API文档了解MarkdownV2转义规则
许可证
MIT许可证-请参阅 许可证 文件
链接
- 电报机器人API
- 电报格式选项
- 模型上下文协议
- GitHub 仓库
- npm包
韩语文档
电报机器人MCP服务器
通过Telegram Bot API发送格式化消息的模型上下文协议(MCP)服务器。
超文本标记语言和 MarkdownV2 支持两种输出模式,支持Telegram中的所有文本实体。
主要功能
- 双解析模式:
HTML(默认,建议)和MarkdownV2可选择输出 - 支持所有Telegram实体:粗体、斜体、下划线、删除线、透露、引用、代码、链接等
- 嵌套格式:
**bold _italic_ bold**使用基于标记的解析器准确呈现 - 自动消息分割:超过4096个字符时在自然边界上自动分割
- 自动回退:转换或传输失败时自动转换为平文
- MCP协议支持:克劳德桌面,克劳德代码,VS代码副本,光标,风帆등
- 内联键盘:支持URL、callback_data等多种按钮
- 照片传输:使用格式化的标题发送照片
- 结构化日志记录:JSON格式日志,可配置的存档策略
安装
npm install -g telegram-chat-bot-mcp```
### 更新
```bash
npm update -g telegram-chat-bot-mcp```
## Telegram机器人设置
### 1)创建@BotFather自动机
1. Telegram中 **@植物学家** 搜索
1. `/newbot` 发送命令后跟随提示
1. 设置机器人名称和用户名(用户名为 `bot`必须以结束)
1. Bot Token安全保存(格式: `<숫자>:<영숫자>`)
### 2)获取Chat ID
- **使用@userinfobot或@getidsbot**:启动机器人时显示用户ID
- **对于组**:将机器人添加到组并发送测试消息后:
https://api.telegram.org/bot/getUpdates``chat.id验证值(组ID为负值,例如:-1001234567890`)
MCP客户端设置
可与多种AI编码工具集成。请选择您使用的工具:
克劳德桌面版
配置文件:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
方法: Claude>设置>开发人员>编辑配置
例子:
{
"mcpServers": {
"telegram": {
"command": "telegram-chat-bot-mcp",
"env": {
"TELEGRAM_BOT_TOKEN": "",
"TELEGRAM_CHAT_ID": ""
}
}
}
}```
### 克劳德代码(CLI)
**配置文件(按优先级排序):**
1. **项目**: `.mcp.json` (团队共享)
1. **用户**: `~/.config/claude-code/mcp.json` (个人全局设置)
**添加为命令:**
```bash
nano ~/.config/claude-code/mcp.json
# 변경 후 재연결
claude mcp reconnect telegram```
**例子:**
```json
{
"mcpServers": {
"telegram": {
"command": "telegram-chat-bot-mcp",
"env": {
"TELEGRAM_BOT_TOKEN": "",
"TELEGRAM_CHAT_ID": ""
}
}
}
}```
### VS代码(GitHub副本)
**要求:** VS Code 1.99或更高版本(2025年3月),启用Agent Mode
**配置文件:**
- **工作空间**: `.vscode/mcp.json` (按项目)
- **用户**:命令面板>“MCP:打开用户配置”
**示例(.vscode/mcp.json):**
```json
{
"servers": {
"telegram": {
"type": "stdio",
"command": "telegram-chat-bot-mcp",
"env": {
"TELEGRAM_BOT_TOKEN": "",
"TELEGRAM_CHAT_ID": ""
}
}
}
}```
### Cursor IDE
**配置文件:**
- **全域**: `~/.cursor/mcp.json`
- **项目**: `.cursor/mcp.json`
**方法:** Settings>直接编辑MCP或文件
**例子:**
```json
{
"mcpServers": {
"telegram": {
"command": "telegram-chat-bot-mcp",
"env": {
"TELEGRAM_BOT_TOKEN": "",
"TELEGRAM_CHAT_ID": ""
}
}
}
}```
### Windsurf IDE(Codeium)
**配置文件:**
- **macOS**: `~/.codeium/windsurf/mcp_config.json`
- **视窗**: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
**方法:** Cascade工具栏>Hammer图标>Configure
**例子:**
```json
{
"mcpServers": {
"telegram": {
"command": "telegram-chat-bot-mcp",
"env": {
"TELEGRAM_BOT_TOKEN": "",
"TELEGRAM_CHAT_ID": ""
}
}
}
}```
## 交付工具(6个)
|工具|说明|
|------|------|
| **`send_telegram_text`** |发送评论信息|
| **`send_telegram_markdown`** |将Markdown转换为HTML或MarkdownV2并发送(推荐)|
| **`send_telegram_with_buttons`** 发送内嵌键盘按钮的消息|
| **`send_telegram_photo`** |图像/照片传输(URL或Telegram file_id)|
| **`markdown_to_telegram_html`** |将Markdown转换为Telegram HTML(实用程序)|
| **`convert_markdown`** |将Markdown转换为HTML或MarkdownV2(实用程序)|
所有工具都默认为 `TELEGRAM_CHAT_ID`使用。个别 `chatId` 可重定义为参数。
### 选择解析模式
`send_telegram_markdown`和 `convert_markdown` 工具是 `parseMode` 支持参数:
模式说明使用时间
|------|------|----------|
| `HTML` (默认)|将Markdown转换为Telegram HTML |大多数情况下建议。转义很简单(3个字符)。 |
| `MarkdownV2` |将Markdown转换为Telegram MarkdownV2 |当需要本机MarkdownV2输出时。转义是严格的(18个字符)。 |
**示例-发送到MarkdownV2:**
```json
{
"tool": "send_telegram_markdown",
"arguments": {
"markdown": "**Bold** and __underline__ text",
"parseMode": "MarkdownV2"
}
}```
## 支持的Markdown语法
|语法|输入| HTML输出| MarkdownV2输出|
|------|------|-----------|----------------|
|粗体| `**bold**` | `bold` | `*bold*` |
|倾斜| `*italic*` | `italic` | `_italic_` |
|下划线| `__underline__` | `underline` | `__underline__` |
取消线| `~~strike~~` | `strike` | `~strike~` |
|透露| `\|\|spoiler\|\|` | `spoiler` | `\|\|spoiler\|\|` |
|行内代码| `` `code` `` | `code` | `` `code` `` |
|代码块| ```````lang\ncode\n``````` | `
code
` | ```````lang\ncode\n``````` |
|引用| `> quote` | `
quote
` | `>quote` |
|链接| `[text](url)` | `text` | `[text](url)` |
|图片| `` |伊莫吉+链接| `` |
|标题| `# H1`, `## H2` |粗标题|粗文本|
|列表| `- item` |项目亮点|转义列表|
表| `\| A \| B \|` | `
` 固定宽度| ``````` ```` 固定宽度|
嵌套 · `**bold _italic_**` · `bold italic` · `*bold _italic_*`
### 转义处理
转义由转换器自动处理:
- **HTML模式**: `&`, `<`, `>` 转义3个字符
- **Markdown V2模式**: `_ * ~ \` > # + - = | { } .!“转义18个字符
- **代码块内部**:最少转义(MarkdownV2中 `` ` ``和 `\`仅)
- **URL内部**:Markdown V2中 `)`和 `\`万
## 环境变量
### 必需
|变量|说明|
|------|------|
| `TELEGRAM_BOT_TOKEN` |从@BotFather收到的Bot Token|
| `TELEGRAM_CHAT_ID` |目标Chat ID(用户或组)|
### 选择(与记录相关)
变量 · 说明 · 默认值
`LOG_LEVEL` 日志级别(DEBUG、INFO、WARN、ERROR) `INFO`
`LOG_DIR` · 日志目录路径 · `./logs`
`LOG_RETENTION_DAYS` · 日志存档天数 · `30`
`LOG_ENABLE_CONSOLE` · 启用控制台输出 · `true`
## 测试```bash
# 환경변수 설정
export TELEGRAM_BOT_TOKEN=""
export TELEGRAM_CHAT_ID=""
# 빌드
npm run build
# 단위 테스트 (154개)
npx vitest run
# 개별 테스트 스크립트
npm run test:telegram:text # 평문 메시지 테스트
npm run test:telegram:markdown # Markdown 변환 테스트
npm run test:mcp:server # MCP 프로토콜 테스트
开发```bash
npm install # 의존성 설치
npm run build # TypeScript 빌드
npm run dev # 개발 모드 실행
npm run lint # 코드 린트
npm run lint:fix # 린트 자동 수정
npx vitest run # 모든 테스트 실행
## 体系结构```
src/
├── server.ts # MCP 서버 및 도구 등록
├── tools/
│ ├── markdownToTelegram.ts # Markdown → Telegram HTML (토큰 기반 파서)
│ ├── markdownToMarkdownV2.ts # Markdown → Telegram MarkdownV2
│ ├── markdownConverter.ts # 듀얼 모드 라우터 (HTML / MarkdownV2)
│ ├── sendTelegramMarkdown.ts # 자동 변환 및 분할 전송
│ ├── sendTelegramText.ts # 평문 전송
│ ├── sendTelegramWithButtons.ts # 인라인 키보드 전송
│ └── sendTelegramPhoto.ts # 사진 전송
├── utils/
│ ├── escapeUtils.ts # HTML 및 MarkdownV2 이스케이프 함수
│ ├── markdownSplitter.ts # 긴 메시지 자동 분할
│ ├── axiosConfig.ts # HTTP 클라이언트 설정
│ └── logger.ts # 구조화된 JSON 로거
└── types/
└── telegram.ts # Telegram API 타입 정의
限制和注意事项
Telegram Bot API限制
- HTML标签:
b,i,u,s,code,pre,a,blockquote,tg-spoiler支援 - 表: `
转换为固定宽度文本(Telegram
`不支持)
- 图像:仅允许HTTPS,限制约10MB的文件大小
- 消息长度:4096个字符限制(超过时自动拆分)
- Markdown V2转义:必须转义所有18个特殊字符(自动处理)
HTML vs Markdown V2比较
| 主题 | HTML | MarkdownV2 |
|---|---|---|
| 转义字符数 | 3个(<, >, &) |
18个(_, *, [, ] 等) |
错误风险低高(如果缺少一个,则为400错误)
嵌套格式 · 明确的XML样式标签 · 基于符号,可模糊
推荐 · 默认选择 · 需要本机V2输出时
保安
Bot Token和Chat ID是敏感信息。
- 千万不要提交到Git
- 不要暴露在公共存储库中
- 秘密信息使用环境变量
- 疑似泄露时通过@BotFather重新发放代币
故障排除
MCP服务器未连接:
- 验证全局安装:
npm install -g telegram-chat-bot-mcp - 验证环境变量设置是否正确
- 更改设置后重新启动AI工具
超时错误(WSL用户):
- 此软件包包含强制IPv4以防止WSL IPv6超时问题
- 如果超时持续,请检查api.telegram.org的网络连接
工具不显示:
- 确保设置文件位于与您使用的工具相匹配的正确位置
- 验证JSON语法是否有效
- 重新启动或重新连接MCP服务器
MarkdownV2传输失败(400 Bad Request):
- 原因可能是未转义的特殊字符。
- 如果切换到HTML模式(默认),处理起来会更宽容。
- 查看Telegram Bot API文档中的MarkdownV2转义规则
许可证
MIT许可证- 许可证 文件引用
链接
- 电报机器人API
- Telegram格式化选项
- 模型上下文协议
- GitHub 仓库
- npm包
- 问题
