telegram-chat-bot-mcp
Advanced tools
An MCP (Model Context Protocol) server for sending messages via Telegram Bot API.
npm install -g telegram-chat-bot-mcp
npx telegram-chat-bot-mcp
/newbot command and follow instructionsbot)<digits>:<alphanumeric_string>)Methods:
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
chat.id value (group IDs are negative, e.g., -1001234567890)This MCP server integrates with various AI coding tools. Choose your tool below:
Configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.jsonAccess: Claude > Settings > Developer > Edit Config
Example:
{
"mcpServers": {
"telegram": {
"command": "telegram-chat-bot-mcp",
"env": {
"TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
"TELEGRAM_CHAT_ID": "<YOUR_CHAT_ID>"
}
}
}
}
Configuration files (by priority):
.mcp.json (at project root)~/.config/claude-code/mcp.jsonAdd server via command:
# Manual method
nano ~/.config/claude-code/mcp.json
# After changes, reconnect
claude mcp reconnect telegram
Example:
{
"mcpServers": {
"telegram": {
"command": "telegram-chat-bot-mcp",
"env": {
"TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
"TELEGRAM_CHAT_ID": "<YOUR_CHAT_ID>"
}
}
}
}
Requirements: VS Code 1.99+ (March 2025), Agent Mode enabled
Configuration files:
.vscode/mcp.json (project-specific)Example (.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>"
}
}
}
}
Configuration files:
~/.cursor/mcp.json.cursor/mcp.jsonAccess: Settings > MCP or direct file edit
Example:
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "telegram-chat-bot-mcp"],
"env": {
"TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
"TELEGRAM_CHAT_ID": "<YOUR_CHAT_ID>"
}
}
}
}
Configuration file:
~/.codeium/windsurf/mcp_config.json%USERPROFILE%\.codeium\windsurf\mcp_config.jsonAccess: Cascade toolbar > Hammer icon > Configure
Example:
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "telegram-chat-bot-mcp"],
"env": {
"TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
"TELEGRAM_CHAT_ID": "<YOUR_CHAT_ID>"
}
}
}
}
send_telegram_text — Send plain text messagessend_telegram_markdown — Convert Markdown to Telegram HTML and send (recommended)send_telegram_with_buttons — Send messages with inline keyboard buttonssend_telegram_photo — Send images/photos (URL or Telegram file_id)markdown_to_telegram_html — Convert Markdown to Telegram HTML (internal utility)All tools use the TELEGRAM_CHAT_ID from environment variables by default. You can optionally override with individual chatId parameter.
| Syntax | Example | Telegram Rendering |
|---|---|---|
| Header | # H1, ## H2 | Bold heading/emphasis |
| Bold | **bold** | bold |
| Italic | *italic* | italic |
| Inline Code | `code` | code |
| Code Block | ```python\ncode\n``` | <pre> block |
| List | - item | • item |
| Table | | A | B | | <pre> monospace |
| Link | [text](url) | Clickable link |
| Image |  | Validated before sending |
| Variable | Description |
|---|---|
TELEGRAM_BOT_TOKEN | Bot Token from @BotFather |
TELEGRAM_CHAT_ID | Target Chat ID (user or group) |
| Variable | Description | Default |
|---|---|---|
LOG_LEVEL | Log level (DEBUG, INFO, WARN, ERROR) | INFO |
LOG_DIR | Log directory path | ./logs |
LOG_RETENTION_DAYS | Days to keep logs | 30 |
LOG_ENABLE_CONSOLE | Enable console output | true |
# Set environment variables first
export TELEGRAM_BOT_TOKEN="<YOUR_BOT_TOKEN>"
export TELEGRAM_CHAT_ID="<YOUR_CHAT_ID>"
# Run tests (requires tsx or built dist/)
npm run build # Build first
# Plain text message test
npm run test:telegram:text
# Markdown conversion test
npm run test:telegram:markdown
# Table rendering test
npm run test:telegram:table-only
# Image sending test
npm run test:telegram:image-wiki
# MCP protocol test
npm run test:mcp:server
# Install dependencies
npm install
# Build TypeScript
npm run build
# Run in dev mode
npm run dev
# Lint code
npm run lint
npm run lint:fix
# Run all tests
npm test
b, i, u, code, pre, a, s, del, ins tags<pre> monospace text (Telegram doesn't support <table>)<b>, <strong>: Bold<i>, <em>: Italic<u>, <ins>: Underline<s>, <strike>, <del>: Strikethrough<code>: Inline code<pre>: Code block<a href="">: LinkLogs are stored in JSON format in the logs/ directory.
Key Events:
sending_message: Message send initiatedmessage_sent: Successfully sentmarkdown_parse_failed: Markdown parsing failed, fallback usedimage_validation_failed: Image validation failedsend_failed: Send operation failedLog retention and level can be configured via environment variables.
⚠️ Bot Token and Chat ID are sensitive information.
MIT License - See LICENSE file
Telegram Bot API를 통해 메시지를 전송하는 MCP (Model Context Protocol) 서버입니다.
npm install -g telegram-chat-bot-mcp
npx telegram-chat-bot-mcp
/newbot 명령어 전송 후 안내 따르기bot으로 끝나야 함)<숫자>:<영숫자>)방법:
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
chat.id 값 확인 (그룹 ID는 음수, 예: -1001234567890)다양한 AI 코딩 도구와 통합 가능합니다. 사용하는 도구를 선택하세요:
설정 파일:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.json접근 방법: Claude > Settings > Developer > Edit Config
예시:
{
"mcpServers": {
"telegram": {
"command": "telegram-chat-bot-mcp",
"env": {
"TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
"TELEGRAM_CHAT_ID": "<YOUR_CHAT_ID>"
}
}
}
}
설정 파일 (우선순위 순):
.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 Code 1.99 이상 (2025년 3월), Agent Mode 활성화
설정 파일:
.vscode/mcp.json (프로젝트별)예시 (.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/mcp.json.cursor/mcp.json접근 방법: Settings > MCP 또는 파일 직접 편집
예시:
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "telegram-chat-bot-mcp"],
"env": {
"TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
"TELEGRAM_CHAT_ID": "<YOUR_CHAT_ID>"
}
}
}
}
설정 파일:
~/.codeium/windsurf/mcp_config.json%USERPROFILE%\.codeium\windsurf\mcp_config.json접근 방법: Cascade 툴바 > Hammer 아이콘 > Configure
예시:
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "telegram-chat-bot-mcp"],
"env": {
"TELEGRAM_BOT_TOKEN": "<YOUR_BOT_TOKEN>",
"TELEGRAM_CHAT_ID": "<YOUR_CHAT_ID>"
}
}
}
}
send_telegram_text — 평문 메시지 전송send_telegram_markdown — Markdown을 Telegram HTML로 변환해 전송 (권장)send_telegram_with_buttons — 인라인 키보드 버튼 포함 메시지 전송send_telegram_photo — 이미지/사진 전송 (URL 또는 Telegram file_id)markdown_to_telegram_html — Markdown을 Telegram HTML로 변환 (내부 유틸리티)모든 도구는 기본적으로 환경변수의 TELEGRAM_CHAT_ID를 사용합니다. 개별 chatId 파라미터로 선택적 재정의 가능합니다.
| 문법 | 예시 | Telegram 렌더링 |
|---|---|---|
| 헤더 | # H1, ## H2 | 굵은 제목/강조 |
| 굵게 | **bold** | bold |
| 기울임 | *italic* | italic |
| 인라인 코드 | `code` | code |
| 코드 블록 | ```python\ncode\n``` | <pre> 블록 |
| 리스트 | - item | • item |
| 표 | | A | B | | <pre> 고정폭 |
| 링크 | [text](url) | 클릭 가능한 링크 |
| 이미지 |  | 전송 전 검증 후 표시 |
| 변수 | 설명 |
|---|---|
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
# 테스트 실행
npm run test:telegram:text # 평문 메시지 테스트
npm run test:telegram:markdown # Markdown 테스트
npm run test:telegram:table-only # 표 렌더링 테스트
npm run test:telegram:image-wiki # 이미지 전송 테스트
npm run test:mcp:server # MCP 프로토콜 테스트
# 의존성 설치
npm install
# TypeScript 빌드
npm run build
# 개발 모드 실행
npm run dev
# 코드 린트
npm run lint
npm run lint:fix
# 모든 테스트 실행
npm test
b, i, u, code, pre, a, s, del, ins 태그만 지원<pre> 고정폭 텍스트로 변환 (Telegram은 <table>을 지원하지 않음)<b>, <strong>: 굵은 글씨<i>, <em>: 기울임<u>, <ins>: 밑줄<s>, <strike>, <del>: 취소선<code>: 인라인 코드<pre>: 코드 블록<a href="">: 링크로그는 logs/ 디렉토리에 JSON 형식으로 저장됩니다.
주요 이벤트:
sending_message: 메시지 전송 시작message_sent: 전송 성공markdown_parse_failed: Markdown 파싱 실패, 폴백 사용image_validation_failed: 이미지 검증 실패send_failed: 전송 작업 실패로그 보관 기간과 레벨은 환경변수로 설정 가능합니다.
⚠️ Bot Token과 Chat ID는 민감 정보입니다.
MCP 서버가 연결되지 않음:
telegram-chat-bot-mcp가 전역 설치되었거나 npx로 접근 가능한지 확인타임아웃 에러 (WSL 사용자):
도구가 표시되지 않음:
MIT License - LICENSE 파일 참조
FAQs
MCP server for Telegram Bot API with Markdown support
The npm package telegram-chat-bot-mcp receives a total of 639 weekly downloads. As such, telegram-chat-bot-mcp popularity was classified as not popular.
We found that telegram-chat-bot-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Socket researchers discovered nine malicious NuGet packages that use time-delayed payloads to crash applications and corrupt industrial control systems.
Security News
Socket CTO Ahmad Nassri discusses why supply chain attacks now target developer machines and what AI means for the future of enterprise security.
Security News
Learn the essential steps every developer should take to stay secure on npm and reduce exposure to supply chain attacks.