{ "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`에 새 키를 추가합니다: ```json { "새사용자": { "bot_token": "새봇토큰", "chat_id": "새chat_id", "api_id": "", "api_hash": "", "phone": "" } } ``` 2. 해당 사용자가 텔레그램에서 봇에 `/start`를 보내면 chat_id를 확인할 수 있습니다. 3. MCP 도구 호출 시 `user` 파라미터에 사용자 키를 지정하면 해당 봇으로 동작합니다. ### 패키지 설치 ```bash uv sync ``` --- ## 2. 실행 ### MCP 서버 (35개 도구) ```bash uv run telegram_extended.py ``` ### 채널 모니터링 ```bash 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 도구 서버 흐름 ```mermaid sequenceDiagram participant Client as MCP 클라이언트
(Claude Desktop 등) participant MCP as MCP 서버
(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. 채널 모니터 흐름 ```mermaid sequenceDiagram participant CH as 텔레그램 채널 participant Monitor as TelegramMonitor
(Telethon User API) participant Log as 로그 출력 Note over Monitor: 로그인 + 이벤트 핸들러 등록 CH->>Monitor: 새 메시지 이벤트 Monitor->>Log: [채널] sender: 메시지 내용 CH->>Monitor: 새 메시지 이벤트 Monitor->>Log: [채널] sender: 메시지 내용 ``` ### 4-3. 전체 시스템 구성도 ```mermaid graph TB subgraph "MCP 도구 서버" A[telegram.py
코어: mcp, _tg, _err] B[tg_messages.py
메시지 9개] C[tg_media.py
미디어 9개] D[tg_chat.py
채팅 8개] E[tg_interactive.py
인터랙티브 9개] F[telegram_extended.py
진입점] 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
Telethon| I[텔레그램 채널] H -->|로깅| J[콘솔 로그] end L[MCP 클라이언트
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`에 추가: ```json { "mcpServers": { "telegram": { "command": "uv", "args": ["run", "/path/to/telegram_extended.py"] } } }

Telegram MCP Server & Channel Monitor

Installation