使用说明

电报机器人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格式日志

安装

npm install -g telegram-chat-bot-mcp

更新

npm update -g telegram-chat-bot-mcp

电报机器人设置

1）通过@BotFather创建机器人

搜索 @植物学家 在Telegram中
发送 /newbot 并遵循指示
设置机器人名称和用户名（用户名必须以结尾 bot)
保存Bot令牌（格式： <digits>:<alphanumeric_string>)

2）获取聊天ID

使用@userinfobot或@getidsbot：启动机器人以查看您的用户ID
对于团体：将机器人添加到组中，发送测试消息，然后调用：
```
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/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>设置>开发人员>编辑配置

例子：

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-chat-bot-mcp",
      "env": {
        "TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
        "TELEGRAM_CHAT_ID": "<YOUR_CHAT_ID>"
      }
    }
  }
}

克劳德代码（CLI）

配置文件（按优先级）：

项目（团队分享）： .mcp.json （项目根）
用户（全球）： ~/.config/claude-code/mcp.json

通过命令添加服务器：

nano ~/.config/claude-code/mcp.json

# After changes, reconnect
claude mcp reconnect telegram

例子：

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-chat-bot-mcp",
      "env": {
        "TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
        "TELEGRAM_CHAT_ID": "<YOUR_CHAT_ID>"
      }
    }
  }
}

VS代码（GitHub副本）

要求： VS代码1.99+（2025年3月），启用代理模式

配置文件：

工作区: .vscode/mcp.json （项目特定）
用户：命令面板>“MCP：打开用户配置”

示例（.vcode/mcp.json）：

{
  "servers": {
    "telegram": {
      "type": "stdio",
      "command": "telegram-chat-bot-mcp",
      "env": {
        "TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
        "TELEGRAM_CHAT_ID": "<YOUR_CHAT_ID>"
      }
    }
  }
}

Cursor IDE

配置文件：

全球: ~/.cursor/mcp.json
项目: .cursor/mcp.json

访问权限： 设置>MCP或直接文件编辑

例子：

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-chat-bot-mcp",
      "env": {
        "TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
        "TELEGRAM_CHAT_ID": "<YOUR_CHAT_ID>"
      }
    }
  }
}

Windsurf IDE（Codeium）

配置文件：

macOS: ~/.codeium/windsurf/mcp_config.json
视窗: %USERPROFILE%\.codeium\windsurf\mcp_config.json

访问权限： 级联工具栏>锤子图标>配置

例子：

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-chat-bot-mcp",
      "env": {
        "TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
        "TELEGRAM_CHAT_ID": "<YOUR_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发送：

{
  "tool": "send_telegram_markdown",
  "arguments": {
    "markdown": "**Bold** and __underline__ text",
    "parseMode": "MarkdownV2"
  }
}

支持的Markdown语法

语法	输入	HTML输出	MarkdownV2输出
大胆	`bold`	`<b>bold</b>`	`bold`
意大利语	`italic`	`<i>italic</i>`	`_italic_`
下划线	`__underline__`	`<u>underline</u>`	`__underline__`
罢工	`~~strike~~`	`<s>strike</s>`	`~strike~`
剧透	`\|\|spoiler\|\|`	`<tg-spoiler>spoiler</tg-spoiler>`	`\|\|spoiler\|\|`
内联代码	`code`	`<code>code</code>`	`code`
代码块	```lang\ncode\n```	`<pre>code</pre>`	```lang\ncode\n```
Blockquote	`> quote`	`<blockquote>quote</blockquote>`	`>quote`
链接	`[text](url)`	`<a href="url">text</a>`	`[text](url)`
图片	`![alt](url)`	带有表情符号前缀的链接	`![alt](url)`
头球 `# H1`, `## H2`	粗体标题	粗体文本
列表	`- item`	要点	逃逸列表
表格	`\| A \| B \|`	`<pre>` 单空间	``` 单空间
嵌套	`bold _italic_`	`<b>bold <i>italic</i></b>`	`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="<YOUR_BOT_TOKEN>"
export TELEGRAM_CHAT_ID="<YOUR_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

发展

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
表格：渲染为 <pre> 等宽文本（Telegram不支持 <table>)
图像：仅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许可证-请参阅许可证文件

链接

韩语文档

电报机器人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

更新

npm update -g telegram-chat-bot-mcp

Telegram机器人设置

1）创建@BotFather自动机

Telegram中 @植物学家 搜索
/newbot 发送命令后跟随提示
设置机器人名称和用户名（用户名为 bot必须以结束）
Bot Token安全保存（格式： <숫자>:<영숫자>)

2）获取Chat ID

使用@userinfobot或@getidsbot：启动机器人时显示用户ID
对于组：将机器人添加到组并发送测试消息后：
```
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/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": "<YOUR_BOT_TOKEN>",
        "TELEGRAM_CHAT_ID": "<YOUR_CHAT_ID>"
      }
    }
  }
}

克劳德代码（CLI）

配置文件（按优先级排序）：

项目: .mcp.json （团队共享）
用户: ~/.config/claude-code/mcp.json （个人全局设置）

添加为命令：

nano ~/.config/claude-code/mcp.json

# 변경 후 재연결
claude mcp reconnect telegram

例子:

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-chat-bot-mcp",
      "env": {
        "TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
        "TELEGRAM_CHAT_ID": "<YOUR_CHAT_ID>"
      }
    }
  }
}

VS代码（GitHub副本）

要求： VS Code 1.99或更高版本（2025年3月），启用Agent Mode

配置文件：

工作空间: .vscode/mcp.json （按项目）
用户：命令面板>“MCP：打开用户配置”

示例（.vscode/mcp.json）：

{
  "servers": {
    "telegram": {
      "type": "stdio",
      "command": "telegram-chat-bot-mcp",
      "env": {
        "TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
        "TELEGRAM_CHAT_ID": "<YOUR_CHAT_ID>"
      }
    }
  }
}

Cursor IDE

配置文件：

全域: ~/.cursor/mcp.json
项目: .cursor/mcp.json

方法： Settings>直接编辑MCP或文件

例子:

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-chat-bot-mcp",
      "env": {
        "TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
        "TELEGRAM_CHAT_ID": "<YOUR_CHAT_ID>"
      }
    }
  }
}

Windsurf IDE（Codeium）

配置文件：

macOS: ~/.codeium/windsurf/mcp_config.json
视窗: %USERPROFILE%\.codeium\windsurf\mcp_config.json

方法： Cascade工具栏>Hammer图标>Configure

例子:

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-chat-bot-mcp",
      "env": {
        "TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
        "TELEGRAM_CHAT_ID": "<YOUR_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：

{
  "tool": "send_telegram_markdown",
  "arguments": {
    "markdown": "**Bold** and __underline__ text",
    "parseMode": "MarkdownV2"
  }
}

支持的Markdown语法

语法	输入	HTML输出	MarkdownV2输出
粗体	`bold`	`<b>bold</b>`	`bold`
倾斜	`italic`	`<i>italic</i>`	`_italic_`
下划线	`__underline__`	`<u>underline</u>`	`__underline__`
取消线	`~~strike~~`	`<s>strike</s>`	`~strike~`
透露	`\|\|spoiler\|\|`	`<tg-spoiler>spoiler</tg-spoiler>`	`\|\|spoiler\|\|`
行内代码	`code`	`<code>code</code>`	`code`
代码块	```lang\ncode\n```	`<pre>code</pre>`	```lang\ncode\n```
引用	`> quote`	`<blockquote>quote</blockquote>`	`>quote`
链接	`[text](url)`	`<a href="url">text</a>`	`[text](url)`
图片	`![alt](url)`	伊莫吉+链接	`![alt](url)`
标题	`# H1`, `## H2`	粗标题	粗文本
列表	`- item`	项目亮点	转义列表
表	`\| A \| B \|`	`<pre>` 固定宽度	``` 固定宽度
嵌套	`bold _italic_`	`<b>bold <i>italic</i></b>`	`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`

测试

# 환경변수 설정
export TELEGRAM_BOT_TOKEN="<YOUR_BOT_TOKEN>"
export TELEGRAM_CHAT_ID="<YOUR_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 프로토콜 테스트

开发

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 支援
表: <pre> 转换为固定宽度文本（Telegram <table>不支持）
图像：仅允许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许可证- 许可证文件引用

使用说明

电报机器人MCP服务器

主要特点

安装

更新

电报机器人设置

1） 通过@BotFather创建机器人

2） 获取聊天ID

MCP客户端配置

克劳德桌面版

克劳德代码（CLI）

VS代码（GitHub副本）

Cursor IDE

Windsurf IDE（Codeium）

提供的工具（6）

解析模式选择

支持的Markdown语法

转义

环境变量

必需

可选（日志记录）

测试

发展

建筑

限制和注意事项

Telegram Bot API约束

HTML与MarkdownV2的比较

安全

故障排除

许可证

链接

韩语文档

电报机器人MCP服务器

主要功能

安装

更新

Telegram机器人设置

1）创建@BotFather自动机

2）获取Chat ID

MCP客户端设置

克劳德桌面版

克劳德代码（CLI）

VS代码（GitHub副本）

Cursor IDE

Windsurf IDE（Codeium）

交付工具（6个）

选择解析模式

支持的Markdown语法

转义处理

环境变量

必需

选择（与记录相关）

测试

开发

体系结构

限制和注意事项

Telegram Bot API限制

HTML vs Markdown V2比较

保安

故障排除

许可证

链接

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器

1）通过@BotFather创建机器人

2）获取聊天ID