Telegram Bot API MCP Server

Telegram Bot API를 위한 Model Context Protocol (MCP) 서버입니다. 이 서버를 사용하면 AI 어시스턴트가 Telegram 봇을 통해 메시지 전송, 미디어 공유, 채팅 관리 등 다양한 작업을 수행할 수 있습니다.

기능

$3

- send_message: 텍스트 메시지 전송
- edit_message_text: 기존 메시지 수정
- delete_message: 메시지 삭제
- forward_message: 메시지 전달
- get_updates: 새로운 업데이트(메시지) 조회

$3

- send_photo: 사진 전송
- send_document: 문서 전송
- send_video: 비디오 전송
- send_audio: 오디오 전송

$3

- get_me: 봇 정보 조회
- get_chat: 채팅 정보 조회

설치 및 설정

$3

``bash
git clone https://github.com/Serverkit-Project/mcp-telegram-bot.git
cd mcp-telegram-bot
`

$3

`bash
npm install
`

$3

.env.example 파일을 .env로 복사하고 Telegram Bot Token을 설정하세요:

`bash
cp env.example .env
`

.env 파일을 열어 다음과 같이 설정하세요:

`env


Telegram Bot Token (필수)

BotFather(@BotFather)에서 봇을 생성하고 토큰을 발급받으세요

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

로그 레벨 (선택, 기본값: info)

LOG_LEVEL=info
`

$3

1. Telegram에서 @BotFather와 대화 시작
2. /newbot 명령어 입력
3. 봇 이름과 username 설정
4. 발급받은 토큰을 .env 파일의 TELEGRAM_BOT_TOKEN에 입력

$3

`bash
npm run build
`

사용 방법

$3

패키지가 npm에 배포된 후:

`bash


npx로 직접 실행 (권장)

npx besir-mcp-telegram-bot

또는 전역 설치

npm install -g besir-mcp-telegram-bot
besir-mcp-telegram-bot
`

$3

`bash


개발 모드로 실행

npm run dev

프로덕션 모드로 실행

npm start
`

MCP 클라이언트 연동

$3

~/.cursor/mcp_settings.json 파일에 다음과 같이 추가:

`json
{
"mcpServers": {
"telegram-bot": {
"command": "npx",
"args": ["-y", "besir-mcp-telegram-bot"],
"env": {
"TELEGRAM_BOT_TOKEN": "your-bot-token-here"
}
}
}
}
`

자세한 설정 방법은 CURSOR_SETUP.md를 참고하세요.

$3

~/Library/Application Support/Claude/claude_desktop_config.json 파일에 추가:

`json
{
"mcpServers": {
"telegram-bot": {
"command": "npx",
"args": ["-y", "besir-mcp-telegram-bot"],
"env": {
"TELEGRAM_BOT_TOKEN": "your-bot-token-here"
}
}
}
}
`

로컬 개발 버전을 사용하는 경우:

`json
{
"mcpServers": {
"telegram-bot": {
"command": "node",
"args": ["/절대/경로/besir_mcp_telegram/dist/index.js"],
"env": {
"TELEGRAM_BOT_TOKEN": "your-bot-token-here"
}
}
}
}
`

도구 사용 예시

$3

`json
{
"name": "send_message",
"arguments": {
"chat_id": 123456789,
"text": "안녕하세요! Telegram Bot API MCP 서버입니다."
}
}
`

$3

`json
{
"name": "send_photo",
"arguments": {
"chat_id": 123456789,
"photo": "https://example.com/image.jpg",
"caption": "예시 이미지입니다."
}
}
`

$3

`json
{
"name": "get_updates",
"arguments": {
"limit": 10
}
}
`

$3

`json
{
"name": "get_me",
"arguments": {}
}
`

API 참고

전체 Telegram Bot API 문서는 다음에서 확인할 수 있습니다:
- Telegram Bot API 공식 문서

개발

$3

`bash
npm test
`

$3

`bash
npm run lint
`

$3

1. src/types/index.ts에 타입 정의 추가
2. src/tools/ 디렉토리에 새 도구 파일 생성
3. src/index.ts`에서 도구를 import하고 등록

라이선스

MIT License

기여

버그 리포트와 기능 제안은 GitHub Issues에 올려주세요.

지원

- Telegram Bot API 문서
- MCP 문서
- GitHub Repository