.
├── telegram.py           # 코어 모듈 (mcp, _tg, _err)
├── 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   # 채널 실시간 모니터링 (메시지 로깅)
├── .env                  # 환경변수 (git 미추적)
├── .env.example          # 환경변수 템플릿
├── pyproject.toml        # 의존성 관리
└── README.md             # 이 문서

cp .env.example .env

uv sync

uv run telegram_extended.py

uv run telegram_monitor.py

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: 결과 문자열 반환

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: 메시지 내용

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

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

telegram.py (코어 모듈)
  ├── BOT_TOKEN: .env에서 로드
  ├── mcp = FastMCP("telegram_mcp")  ← 공유 인스턴스
  ├── _tg(): httpx로 Telegram Bot API 호출하는 공통 함수
  └── _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 클래스: 모든 설정을 os.getenv()로 관리
  ├── TelegramMonitor 클래스:
  │   ├── _on_new_message(): NewMessage 이벤트 핸들러 (메시지 로깅)
  │   └── run(): 로그인 + 채널 이벤트 구독 + 연결 유지
  └── asyncio.run(monitor.run())으로 실행