Telegram Bot API MCP Server

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

기능

메시지 관리

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

미디어 전송

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

봇/채팅 정보

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

설치 및 설정

1. 프로젝트 클론 또는 다운로드

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

2. 의존성 설치

npm install

3. 환경 변수 설정

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

cp env.example .env

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

# Telegram Bot Token (필수)
# BotFather(@BotFather)에서 봇을 생성하고 토큰을 발급받으세요
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

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

4. Telegram Bot Token 발급받기

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

5. 빌드

npm run build

사용 방법

NPM에서 설치 (권장)

패키지가 npm에 배포된 후:

# npx로 직접 실행 (권장)
npx besir-mcp-telegram-bot

# 또는 전역 설치
npm install -g besir-mcp-telegram-bot
besir-mcp-telegram-bot

로컬 개발 모드

# 개발 모드로 실행
npm run dev

# 프로덕션 모드로 실행
npm start

MCP 클라이언트 연동

Cursor 설정 (권장)

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

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

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

Claude Desktop 설정

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

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

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

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

도구 사용 예시

메시지 전송

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

사진 전송

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

업데이트 조회

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

봇 정보 조회

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

API 참고

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

• Telegram Bot API 공식 문서

개발

테스트 실행

npm test

린트 실행

npm run lint

새로운 도구 추가하기

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

라이선스

MIT License

기여

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

지원

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