Telegram Bot API 기반 MCP 도구 서버 + Telethon User API 기반 채널 실시간 모니터링 시스템.

---

📁 파일 구조

.
├── telegram.py              # 코어 모듈 (mcp, _tg, _err, config 로드)
├── tg_messages.py           # 메시지 CRUD 도구 (9개)
├── tg_media.py              # 미디어 전송 도구 (9개)
├── tg_chat.py               # 채팅 정보/관리 도구 (8개)
├── tg_interactive.py        # 인터랙티브/유틸 도구 (9개)
├── telegram_extended.py     # MCP 서버 진입점 (총 35개 도구)
├── telegram_monitor.py      # 채널 실시간 모니터링 (메시지 로깅)
├── telegram_config.json     # 사용자별 봇 설정 + 공통 설정
├── pyproject.toml           # 의존성 관리
└── README.md                # 이 문서

---

1. 환경 설정

telegram_config.json 설정 (필수)

이 파일이 없으면 MCP 서버와 모니터가 실행되지 않습니다. 반드시 프로젝트 루트(telegram-mcp/)에 telegram_config.json을 생성하고, 최소 1명의 사용자 봇 정보를 입력한 뒤 사용하세요.

모든 설정은 telegram_config.json 파일 하나로 관리합니다.

{
  "default_user": "gayeon",
  "settings": {
    "monitor_mode": "buffer",
    "buffer_minutes": 5,
    "immediate_debounce_sec": 3,
    "buffer_max_messages": 50,
    "session_name": "telegram_session"
  },
  "gayeon": {
    "bot_token": "BOT_TOKEN_HERE",
    "chat_id": "CHAT_ID_HERE",
    "api_id": "",
    "api_hash": "",
    "phone": ""
  }
}

구조 규격

키	타입	필수	설명
default_user	string	O	user 미지정 시 기본으로 사용할 사용자 키
settings	object	O	공통 설정
settings.monitor_mode	string	-	모니터링 모드 (buffer / immediate)
settings.buffer_minutes	int	-	버퍼 모드 수집 간격(분)
settings.immediate_debounce_sec	int	-	즉시 모드 디바운스(초)
settings.buffer_max_messages	int	-	버퍼 최대 메시지 수
settings.session_name	string	-	Telethon 세션 파일명
{사용자}	object	O (1명 이상)	사용자별 봇 설정
{사용자}.bot_token	string	O	Bot API 토큰 (@BotFather 발급)
{사용자}.chat_id	string	O	봇과 대화할 채팅 ID
{사용자}.api_id	string	-	User API 앱 ID (my.telegram.org)
{사용자}.api_hash	string	-	User API 앱 해시
{사용자}.phone	string	-	로그인 전화번호 (+821012345678)

사용자 추가 방법

1. telegram_config.json에 새 키를 추가합니다:

{
  "새사용자": {
    "bot_token": "새봇토큰",
    "chat_id": "새chat_id",
    "api_id": "",
    "api_hash": "",
    "phone": ""
  }
}

2. 해당 사용자가 텔레그램에서 봇에 /start를 보내면 chat_id를 확인할 수 있습니다.
3. MCP 도구 호출 시 user 파라미터에 사용자 키를 지정하면 해당 봇으로 동작합니다.

패키지 설치

uv sync

---

2. 실행

MCP 서버 (35개 도구)

uv run telegram_extended.py

채널 모니터링

uv run telegram_monitor.py

최초 실행 시 Telethon 로그인 인증(전화번호 → 인증코드)이 필요합니다. 이후 telegram_session.session 파일에 세션이 저장되어 자동 로그인됩니다.

---

3. MCP 도구 목록 (35개)

3-1. 메시지 CRUD — tg_messages.py (9개)

도구	API	설명
telegram_send_message	sendMessage	텍스트 메시지 전송 (Markdown/HTML)
telegram_get_updates	getUpdates	봇 수신 메시지 조회 (offset 중복 방지)
telegram_edit_message	editMessageText	메시지 수정
telegram_delete_message	deleteMessage	메시지 삭제
telegram_delete_messages	deleteMessages	메시지 복수 삭제
telegram_forward_message	forwardMessage	포워드 (출처 표시)
telegram_forward_messages	forwardMessages	복수 포워드
telegram_copy_message	copyMessage	복사 (출처 없음)
telegram_copy_messages	copyMessages	복수 복사

3-2. 미디어 전송 — tg_media.py (9개)

도구	API	설명
telegram_send_photo	sendPhoto	사진 전송
telegram_send_document	sendDocument	파일/문서 전송
telegram_send_video	sendVideo	동영상 전송
telegram_send_audio	sendAudio	오디오 전송
telegram_send_voice	sendVoice	음성 메시지 전송
telegram_send_animation	sendAnimation	GIF/애니메이션 전송
telegram_send_video_note	sendVideoNote	둥근 비디오 전송
telegram_send_media_group	sendMediaGroup	미디어 그룹(앨범) 전송
telegram_send_sticker	sendSticker	스티커 전송

3-3. 채팅 정보/관리 — tg_chat.py (8개)

도구	API	설명
telegram_get_chat	getChat	채팅 상세 조회
telegram_get_chat_members_count	getChatMemberCount	멤버 수 조회
telegram_get_me	getMe	봇 정보 조회
telegram_pin_message	pinChatMessage	메시지 고정
telegram_unpin_message	unpinChatMessage	고정 해제
telegram_ban_user	banChatMember	사용자 차단
telegram_unban_user	unbanChatMember	차단 해제
telegram_send_chat_action	sendChatAction	채팅 액션 전송 (입력 중...)

3-4. 인터랙티브/유틸 — tg_interactive.py (9개)

도구	API	설명
telegram_send_poll	sendPoll	투표 생성
telegram_send_with_buttons	sendMessage (inline_keyboard)	인라인 버튼 메시지
telegram_answer_callback_query	answerCallbackQuery	콜백 쿼리 응답
telegram_send_location	sendLocation	위치 전송
telegram_send_venue	sendVenue	장소 전송
telegram_send_contact	sendContact	연락처 전송
telegram_send_dice	sendDice	주사위/랜덤 전송
telegram_set_message_reaction	setMessageReaction	메시지 리액션
telegram_get_file	getFile	파일 정보/다운로드 URL 조회

3-5. 채널 모니터 — telegram_monitor.py

지정한 텔레그램 채널의 메시지를 실시간 수신하여 로그로 기록합니다.

모니터링할 채널은 telegram_monitor.py의 Config.MONITOR_CHANNELS 리스트에 직접 추가합니다.

---

4. 시퀀스 다이어그램

4-1. MCP 도구 서버 흐름

sequenceDiagram
    participant Client as MCP 클라이언트<br/>(Claude Desktop 등)
    participant MCP as MCP 서버<br/>(telegram_extended.py)
    participant TG as Telegram Bot API

    Client->>MCP: 도구 호출 (예: telegram_send_message)
    MCP->>MCP: Pydantic 입력 검증
    MCP->>TG: POST /bot{TOKEN}/{method}
    TG-->>MCP: JSON 응답
    MCP-->>Client: 결과 문자열 반환

4-2. 채널 모니터 흐름

sequenceDiagram
    participant CH as 텔레그램 채널
    participant Monitor as TelegramMonitor<br/>(Telethon User API)
    participant Log as 로그 출력

    Note over Monitor: 로그인 + 이벤트 핸들러 등록

    CH->>Monitor: 새 메시지 이벤트
    Monitor->>Log: [채널] sender: 메시지 내용

    CH->>Monitor: 새 메시지 이벤트
    Monitor->>Log: [채널] sender: 메시지 내용

4-3. 전체 시스템 구성도

graph TB
    subgraph "MCP 도구 서버"
        A[telegram.py<br/>코어: mcp, _tg, _err]
        B[tg_messages.py<br/>메시지 9개]
        C[tg_media.py<br/>미디어 9개]
        D[tg_chat.py<br/>채팅 8개]
        E[tg_interactive.py<br/>인터랙티브 9개]
        F[telegram_extended.py<br/>진입점]
        A --> B & C & D & E
        F -->|import| B & C & D & E
        B & C & D & E -->|Bot API| G[Telegram Bot API]
    end

    subgraph "채널 모니터"
        H[telegram_monitor.py] -->|User API<br/>Telethon| I[텔레그램 채널]
        H -->|로깅| J[콘솔 로그]
    end

    L[MCP 클라이언트<br/>Claude Desktop 등] -->|MCP 프로토콜| F

    style A fill:#4a9eff,color:#fff
    style F fill:#4a9eff,color:#fff
    style H fill:#ff6b6b,color:#fff

---

5. MCP 클라이언트 연결

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": ["run", "/path/to/telegram_extended.py"]
    }
  }
}

봇 토큰 등 모든 설정은 telegram_config.json에서 관리되므로 env는 불필요합니다.

---

6. chat_id 확인 방법

대상	방법
본인 ID	@userinfobot 에 /start
그룹 ID	그룹에 @userinfobot 초대 후 /start
채널 ID	web.telegram.org URL에서 숫자 확인

그룹·채널 ID는 보통 음수(예: -1001234567890)입니다.

---

7. 주의사항

• 그룹·채널 관리 도구(pin, ban 등)는 봇 관리자 권한 필요
• telegram_get_updates는 Webhook과 동시 사용 불가
• Bot API 속도 제한: 동일 채팅 초당 1건, 분당 20건 이하 권장
• telegram_monitor.py는 User API 사용 → 개인 계정 로그인 필요 (봇 아님)

---

Contributors

이름	역할
Gayeon Lee (@ruchiayeon)	Creator & Developer
Claude (Anthropic)	AI Pair Programmer

Contact

• Email: [email protected]

---

AI Instructions (LLM Context)

이 섹션은 AI 에이전트가 이 프로젝트를 이해하고 작업할 때 참고하는 구조화된 컨텍스트입니다.

Project Overview

• 프로젝트명: Telegram MCP Server & Channel Monitor
• 언어: Python 3.14+
• 패키지 매니저: uv
• 핵심 의존성: httpx, mcp (FastMCP), pydantic, telethon

Architecture

telegram.py (코어 모듈)
  ├── telegram_config.json에서 사용자별 설정 로드
  ├── mcp = FastMCP("telegram_mcp")  ← 공유 인스턴스
  ├── _tg(method, payload, user): 사용자별 봇으로 Telegram Bot API 호출
  ├── get_chat_id(user): 사용자의 chat_id 반환
  └── _err(): 예외 → 사용자 친화적 에러 문자열 변환

tg_messages.py (메시지 CRUD 9개 도구)
  ├── send_message, get_updates, edit, delete, delete_messages
  └── forward, forward_messages, copy, copy_messages

tg_media.py (미디어 전송 9개 도구)
  └── photo, document, video, audio, voice, animation, video_note, media_group, sticker

tg_chat.py (채팅 관리 8개 도구)
  └── get_chat, members_count, get_me, pin, unpin, ban, unban, chat_action

tg_interactive.py (인터랙티브/유틸 9개 도구)
  └── poll, buttons, callback, location, venue, contact, dice, reaction, get_file

telegram_extended.py (진입점)
  ├── import tg_messages, tg_media, tg_chat, tg_interactive
  └── mcp.run()으로 실행 시 총 35개 도구 제공

telegram_monitor.py (독립 실행 스크립트)
  ├── Telethon User API 사용 (Bot API 아님)
  ├── Config 클래스: telegram_config.json에서 설정 로드
  ├── TelegramMonitor 클래스:
  │   ├── _on_new_message(): NewMessage 이벤트 핸들러 (메시지 로깅)
  │   └── run(): 로그인 + 채널 이벤트 구독 + 연결 유지
  └── asyncio.run(monitor.run())으로 실행

Key Patterns

• 모듈 분리 패턴: telegram.py가 코어(mcp, _tg, _err)를 제공하고, 4개 도구 모듈(tg_messages, tg_media, tg_chat, tg_interactive)이 기능별로 도구를 등록. telegram_extended.py는 진입점으로 모든 모듈을 import 후 mcp.run() 실행.
• 입력 검증: 모든 MCP 도구는 Pydantic BaseModel로 입력 검증 (ConfigDict(extra="forbid") 사용).
• 에러 처리: _err() 함수로 httpx 예외를 사용자 친화적 한국어 문자열로 변환.
• 설정 관리: telegram_config.json 단일 파일로 사용자별 봇 설정 + 공통 설정 관리.
• 비동기: httpx.AsyncClient (MCP 서버), Telethon + asyncio (모니터).

File Modification Rules

• telegram.py 수정 시: 4개 도구 모듈이 mcp, _tg, _err, get_chat_id, DEFAULT_USER를 import하므로 이 인터페이스 유지 필요.
• 새 MCP 도구 추가 시: 해당 카테고리의 tg_*.py 파일에 Pydantic 모델 + @mcp.tool() 데코레이터로 추가.
• 새 카테고리 추가 시: tg_newcategory.py 생성 후 telegram_extended.py에 import 추가.
• 모니터링 채널 변경 시: telegram_monitor.py의 Config.MONITOR_CHANNELS 리스트 수정.

Configuration

모든 설정은 telegram_config.json 단일 파일로 관리됩니다. 상세 규격은 상단 "1. 환경 설정" 참조.