Telegram MCP Server & Channel Monitor

Telegram MCP Server & Channel Monitor

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

구조 규격

사용자 추가 방법

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개)

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

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

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

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는 보통 음수(예: -1001234567890)입니다.

7. 주의사항

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

Contributors

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. 환경 설정" 참조.