.
├── 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                # 이 문서

{
  "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": ""
  }
}

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

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"]
    }
  }
}

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())으로 실행