F
licenseNot graded
qualityD
maintenanceConnects AI agents to Telegram via the official TDLib library, enabling tools like getting user info, listing dialogs, and searching messages.
-
telegram-mcp-server
by Steph-ux
telegram-mcp-server
Telegram MCP 서버 — Telethon 기반, 영구 클라이언트, 플러드 안전, 9개의 그룹화된 도구.
코드에 API 키 없음. 세션 파일은 로컬에 저장됩니다. 사용자 계정(2FA) 및 봇과 함께 작동합니다.
1. 설치
git clone <this-repo> telegram-mcp-server
cd telegram-mcp-server
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
pip install -e .API 자격 증명 가져오기
my.telegram.org로 이동
전화번호로 로그인
앱 생성 → API ID 및 API Hash 받기
일회성 인증
# User account (with 2FA support)
export TG_API_ID=12345
export TG_API_HASH="your_hash_here"
telegram-mcp-server --auth --phone +33612345678
# Or via MCP tool: tg_session(action="auth", api_id=12345, api_hash="...", phone="+33612345678")Related MCP server: telegram-mcp
2. MCP 클라이언트에 등록
Claude Desktop / OpenCode
{
"mcpServers": {
"telegram": {
"command": "telegram-mcp-server",
"env": {
"TG_API_ID": "12345",
"TG_API_HASH": "your_hash_here"
}
}
}
}PATH에 없는 경우:
{
"mcpServers": {
"telegram": {
"command": "/path/to/.venv/bin/python",
"args": ["-m", "telegram_mcp_server"],
"env": {
"TG_API_ID": "12345",
"TG_API_HASH": "your_hash_here"
}
}
}
}Docker
docker build -t telegram-mcp .
docker run -i --rm \
-v ~/.telegram-mcp/sessions:/root/.telegram-mcp/sessions \
-e TG_API_ID=12345 \
-e TG_API_HASH="your_hash" \
telegram-mcp3. 도구 카탈로그 (9개 도구, 8개 작업)
tg_session — 세션 관리
action | Required args | Description |
|
| 인증 (2FA 지원) |
| — | 로그인 상태 확인 |
| — | 세션 삭제 |
tg_message — 보내기, 전달, 삭제, 답장
action | Required args | Description |
|
| 메시지 보내기 |
|
| 메시지 전달 |
|
| 메시지 삭제 |
|
| 메시지에 답장 |
tg_chat — 채팅 작업
action | Required args | Description |
| — | 최근 채팅 목록 |
|
| 채팅 정보 가져오기 |
|
| 채팅 멤버 목록 |
|
| 채팅 나가기 |
tg_search — 검색
action | Required args | Description |
|
| 메시지 검색 (선택적으로 |
|
| 연락처/사용자 검색 |
|
| 채널 검색 |
tg_history — 채팅 기록
action | Required args | Description |
|
| 메시지 기록 가져오기 |
|
| 미디어 전용 기록 가져오기 |
|
| 파일 전용 기록 가져오기 |
tg_user — 사용자 작업
action | Required args | Description |
| — | 자신의 정보 가져오기 |
|
| 사용자 정보 가져오기 |
|
| 사용자 차단 |
|
| 사용자 차단 해제 |
tg_media — 미디어 보내기
action | Required args | Description |
|
| 사진 보내기 |
|
| 동영상 보내기 |
|
| 문서 보내기 |
|
| 음성 메모 보내기 |
tg_channel — 채널 관리
action | Required args | Description |
|
| 슈퍼그룹/채널 만들기 |
|
| 채널 가입 |
|
| 채널 나가기 |
|
| 채널 정보 가져오기 |
tg_draft — 임시 메시지
action | Required args | Description |
|
| 임시 저장 |
| — | 모든 임시 메시지 목록 |
|
| 임시 메시지 삭제 |
4. 환경 변수
Variable | Default | Description |
|
| Telegram API ID (my.telegram.org에서) |
|
| Telegram API Hash |
|
| 세션 파일 위치 |
5. 안전
속도 제한: 보내기 작업은 분당 5회로 제한됩니다. 읽기 작업은 무제한입니다.
FloodWaitError 자동 재시도: 필요한 시간만큼 대기합니다 (최대 5분).
세션 파일: 로컬 전용, git에 커밋되지 않습니다.
2FA 지원: 2단계 인증 계정 완전 지원.
6. MCP 리소스
tg://version— 서버 버전tg://session/status— 로그인 상태
라이선스
MIT
This server cannot be deployed
Maintenance
ActivitySlowing
ResponsivenessNo issues
Related MCP Connectors
Telegram: FASTEST real time Telegram API. Retrieve channel's info and messages in milliseconds..
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
I use your linked Telegram MTProto session (Integrations → Telegram) to list groups, members, and s…
Telegram CRM: manage contacts, conversations, tickets, campaigns and analytics.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Telegram Bot API for sending messages, photos, editing messages, answering callbacks, and fetching updates.MIT
- AlicenseNot gradedqualityBmaintenanceEnables sending Telegram messages, photos, and documents, and retrieving bot information through the Telegram Bot API.31 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with a user's Telegram account: list chats, read history, search, and send messages through Telegram's MTProto API.1MIT