Telegram MCP — Next Generation

프로덕션 지향 Telegram 통합으로, MCP 호환 클라이언트를 위한 것이며 LoneVertex가 유지 관리하고 Telethon과 Model Context Protocol을 기반으로 구축되었습니다. 이 저장소는 업스트림 Telegram 기능 범위를 유지하면서 명시적 도구 티어, 실패 시 차단(fail-closed) 변경 제어, 키 기반 동시성 제한, 제한된 재시도, 로컬 SQLite/FTS5 캐싱, 더 안전한 미디어 경로, 패키지 진입점, 재현 가능한 CI를 추가합니다.

기본 방침: 로컬 stdio, core 도구 티어, Telegram 쓰기 없음, 파괴적 작업 없음, 검증되지 않은 파일시스템 루트 없음.

프로젝트 거버넌스: 기여 안내 · 보안 정책 · Apache License 2.0

포함 내용

이 구현은 128개 도구를 등록합니다: 계정, 채팅, 연락처, 메시지, 그룹, 미디어, 프로필, 폴더, 수신 이벤트를 다루는 업스트림 125개 도구에 더해 cache_health, search_cached_messages, sync_chat_cache가 포함됩니다. 업스트림 출처는 커밋 52cca204d945e4ec292801a9d972334c0c2a4b63에 보존되며, 차세대 패키지 버전은 4.0.1입니다.

티어를 선택하려면 TELEGRAM_MCP_TIER를 설정하세요. 티어 선택은 어떤 도구가 등록될지 결정합니다. TELEGRAM_SEND_ENABLED는 쓰기 작업이 실행될 수 있는지 여부를 독립적으로 제어하며, TELEGRAM_DESTRUCTIVE_ENABLED는 파괴적/관리자 작업을 위한 두 번째 게이트입니다. 게이트가 호출을 차단하면 서버는 구조화된 nothing_sent 또는 nothing_done 응답을 반환합니다.

Related MCP server: telegram-mcp

빠른 시작

Python 3.11 또는 3.12를 사용하세요. my.telegram.org/apps에서 Telegram API 자격 증명을 얻은 다음, 포함된 세션 생성기를 사용해 MCP 프로세스 외부에서 인증된 세션을 생성하세요.

git clone https://github.com/LoneVertex/telegram-mcp-nextgen.git
cd telegram-mcp-nextgen
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# edit .env with TELEGRAM_API_ID, TELEGRAM_API_HASH, and an authorized session
telegram-mcp

패키지 개발 및 릴리스 검증을 위해:

pip install -e '.[dev]'
pytest -q
ruff check telegram_mcp/config.py telegram_mcp/core telegram_mcp/db telegram_mcp/models
mypy --explicit-package-bases telegram_mcp/config.py telegram_mcp/core telegram_mcp/db telegram_mcp/models
python -m build

서버는 의도적으로 비대화형입니다. 시작 전에 telegram-mcp-generate-session을 사용하고 생성된 세션 문자열을 비공개로 유지하세요. .env, Telethon .session 파일, API 해시, 세션 문자열을 절대 커밋하지 마세요.

구성

비밀 정보가 없는 전체 템플릿은 .env.example에 있습니다. 중요 제어 항목은 아래에 요약되어 있습니다.

구성 구성은 부작용이 없습니다. 자격 증명과 인증은 로컬 도구가 패키지를 가져올 때가 아니라 실제 클라이언트가 시작될 때 확인됩니다. 런타임 상태는 캐시나 세션 작업이 필요할 때만 소유자 전용 디렉터리 아래에 생성됩니다.

MCP 클라이언트 및 전송

데스크톱 MCP 클라이언트를 위한 비밀 정보 없는 예시는 config/mcp-configs.md를 참조하세요. 로컬 stdio가 선호됩니다. 장기 실행되는 로컬 서비스를 위해 Streamable HTTP를 사용할 수 있습니다:

MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8765

인증되지 않은 HTTP 엔드포인트를 공개 인터넷에 직접 노출하지 마세요. 리버스 프록시를 사용하는 경우 인증, TLS, 허용 호스트, 허용 오리진, 네트워크 검게 를 구셩하세요. MCP_ALLOWED_HOSTS가 구셩되면 서버는 MCP DNS 리바인딩 보호를 유지합니다.

동시성 및 안정성

각 계정은 키 기반 이벤트 뮤텍스와 토큰 버킷으으로 보호됩니다. 같인 계정을 공유하 는 호출은 어터 경계에서 직렬화되며, 서로 다르런 계정 라벨 간의 읽기 전위 멀틀계정 fan-out은 계속 가능합니다.

FloodWait과 르시적인 연걸 실패에는 지수 백오프와 지터를 포암한 하거 계정은 재시도 정책를 사욕합니다. 동일한 Telegram 언증 키를 여려 프루세스가 동시에 사욕하지 못하도록 세션 수준의 조션 잠금(advisory lock)이 유지됩니다.

로컬 캐시에는 SQlite WAL 모드, 외래 키, 단기간 연결, 명션 명시적 의, 팅/날짜/발신자/주제 접근 인자, 그리고 검색용 FTS5를 사욕합니다. 동기화는 키p포인트를 저장하고 UPSERT를 사욕하므로 수정사항이 중복되지 않고 반영됩니다. SQlite 작업, 디렉터리 생성, 무결성 검사는 이벤트 루프를 막지 않도록 작업자(worker) 텃에서 수씽됩니다.

미디어 및 파일시스템 안전

파일 도구는 클라이언트 MCP Roots 또는 명시적 서버 측 루트가 필요합니다. TELEGRAM_ALLOW_SERVER_ROOTS_FALLBACK=true를 의도적으로 설정하지 않는 한, 비어 있거나 검증할 수 없는 루트는 전면 거부(deny-all)로 동작합니다. 경로는 설정된 루트 아래로만 해석되며, 상위 경로 이동 시토(traversal)와 NUL 바이트는 거부되고, 심볼릭 링크 탈출은 거부되며, 미디어 크기 제한이 적용되고, 생성된 파일은 소유자 전용 권한을 갖습니다. 새로운 보안 프리미티브는 청크 단위 읽기와 원자적 출력 교체를 지원합니다.

Telegram 텍스트, 캡션, 이름, 버튼 라벨, 미디어 메타데이터, 수신 이벤트 필드는 신뢰할 수 없는 사용자 콘텐츠입니다. 위생 처리(sanitization)와 노출 대상 주석은 업스트림에서 유지되며, 모델은 이 필드를 지시로 취급해서는 안 합니다.

Docker

이미지는 2단계 Python 3.12 빌드를 사용하며, UID 10001로 실행되되고, 상태를 /var/lib/telegram-mcp에 저장하며, 런타임에만 자격 증명을 받습니다.

cp .env.example .env
# edit .env
podman compose up --build
# or: docker compose up --build

Compose는 HTTP를 127.0.0.1:8765에 바인딩하고, 영구 명명 볼륨을 사용하며, Linux capabilities를 제거하고, no-new-privileges를 사용하며, 읽기 전용 루트 파일시스템을 마운트하고, 제한된 /tmp를 제공합니다. 이번 배포에 사용된 샌드박스에서는 Docker를 사용할 수 없어 컨테이너 빌드는 실행되지 않았습니다. CI 워크플로우는 Docker 가능한 러너에서 이를 검증합니다.

개발 및 릴리스 검증

.github/workflows/ci.yml 통합 워크플로우는 Python 3.11과 3.12에서 실행되고, 상속받은 업스트림 회귀 테스트 스위트와 차세대 테스트를 실행하며, 새 운영 레이어에 대한 엄격한 Ruff 검사를 실행하고, 명시한 패키지 사로 mypy 검사을 실행하며, 패키지를 컴파일하고, wheel/sdist를 빌드하며, 선언한 의존성을 검사하고, Docker 이미즈와 Compose 설정을 검합니다.

업스트림의 라이브 Telegram 어댑터는 상속된 모의 회귀 스위트로 계속 검증을 유지하며, 로컬 안정성/보안 모듈은 별도의 테스트와 적용 범호를 보유합니다.

소유권, 호환성 및 앞서 온 것

프로젝트 관리: LoneVertex.

호환성을 위해 루트 main.py, 업스트림 툴 모듈 이름, 세션 생성기, 계정 라벨, 프록시 설정, MCP 전송 변수, 레거시 노출 필터, 업스트림 Apache-2.0 라이선스를 유지합니다. 새 패키지 진입점은 telegram_mcp.runner:main이며, python -m telegram_mcp를 지원합니다. 업스트림 원본과 저자 표시는 Git 기록과 AUDIT_REPORT.md에 계속 남아 있습니다.

문제 해결

시작 시 세션이 설정되지 않았다는 메시지가 나오면 인증된 세션을 생성하고 TELEGRAM_SESSION_STRING 또는 유효한 파일 세션 이름을 설정하세요. 쓰기 동작이 MutationDisabled를 반환하면 TELEGRAM_SEND_ENABLED=true로 설정하고 재시작하고, 삭제나 관리 작업의 경우 TELEGRAM_DESTRUCTIVE_ENABLED=true도 설정하세요. 파일 도구가 루트를 이용할 수 없다고 하면 클라이언트 MCP Roots를 구성하거나 인자로 사용 가능한 서버 측 허용 루트를 지정하세요. FloodWait가 설정된 최대 시간을 초과하면 무한히 기다리는 대신 의도적으로 호출이 반환됩니다. cache_health를 사용하면 Telegram에 접촉하지 않고 로컬 SQLite/FTS5 무결성을 검사할 수 있습니다.

참고 자료

라이선스

Apache License 2.0. LICENSE를 참조하세요.