telegram-mcp

내 텔레그램(개인 계정)의 채팅 폴더, 채널/그룹 목록, 최근 메시지를 읽기 전용으로 노출하는 원격 MCP 서버입니다. ChatGPT와 Claude에 "커스텀 커넥터"로 등록해서 사용합니다.

봇 API가 아니라 텔레그램 사용자 계정으로 로그인(MTProto, Telethon)하기 때문에, 봇을 초대하지 않은 채널이나 "채팅 폴더" 같은 개인 계정 전용 기능도 볼 수 있습니다. 대신 세션 문자열이 계정 전체에 대한 접근 권한과 동일하므로 보안에 각별히 주의하세요.

제공 도구 (전부 읽기 전용)

일부 슈퍼그룹은 "포럼 토픽" 기능으로 하나의 방 안에 "차트 스쿨", "공지방" 같은 하위 주제방이 나뉘어 있습니다. 이런 하위 주제방은 별도의 대화(dialog)가 아니라서 list_dialogs/list_chats_in_folder에는 안 보입니다 — list_topics로 먼저 목록을 확인하고, get_recent_messages/search_messages의 topic 인자로 주제명을 넘겨서 읽으세요.

get_recent_messages/search_messages가 반환하는 각 메시지에는 has_media/media_type이 포함됩니다. media_type이 "photo"인 메시지를 실제로 보려면 그 메시지의 id를 get_message_photo(chat, message_id)에 넘기세요 (문서/동영상 등 다른 첨부파일은 아직 다운로드를 지원하지 않습니다).

메시지 발송 등 쓰기 기능은 의도적으로 구현하지 않았습니다.

Related MCP server: telegram-mcp

1. 사전 준비: Telegram API 자격증명 발급

1. https://my.telegram.org 접속 → 본인 전화번호로 로그인.

2. API development tools 메뉴에서 새 앱 생성 (이름/플랫폼은 아무 값이나 가능).

3. 발급된 api_id, api_hash 를 기록해둡니다. (제3자에게 대행 불가 — 본인 인증 필요)

2. 설치

python3 -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env

.env 에 TG_API_ID, TG_API_HASH 를 채워 넣습니다. (인증/MCP_* 값은 4단계에서 채웁니다.)

3. 텔레그램 로그인 (최초 1회, 대화형)

source .venv/bin/activate
set -a; source .env; set +a
python scripts/login.py

전화번호 입력 → 텔레그램 앱(또는 SMS)으로 받은 로그인 코드 입력 → (2단계 인증을 켜둔 경우) 비밀번호 입력. 완료되면 세션 문자열이 출력됩니다. 이 값을 .env의 TG_SESSION_STRING에 저장하세요.

세션 문자열은 비밀번호와 동일한 권한을 가집니다. 절대 커밋하거나 공유하지 마세요. (.gitignore에 .env가 이미 포함되어 있습니다.)

4. 외부 공개 URL 먼저 확보 (Cloudflare Tunnel)

인증 방식(특히 GitHub OAuth)을 설정하려면 외부에서 접근 가능한 URL이 먼저 필요하므로, 서버를 켜기 전에 터널부터 열어 URL을 확보합니다.

지금 당장 테스트용 (임시 URL)

cloudflared tunnel --url http://localhost:8811

콘솔에 출력되는 https://xxxx.trycloudflare.com 을 기록해두세요. (아직 서버가 안 떠 있어서 502가 떠도 정상 — URL만 먼저 확보하는 단계입니다. 프로세스를 끄면 URL도 사라짐 — 테스트/검증용.)

나중에: 본인 서버 + 도메인으로 영구 운영

1. 이 저장소를 실제로 상시 켜둘 서버에 clone.

2. Cloudflare Zero Trust에서 Named Tunnel 생성 후 본인 도메인의 서브도메인(예: telegram-mcp.example.com)을 http://localhost:8811 로 라우팅. 이 고정 도메인을 아래 단계들의 URL로 사용하면 됩니다.

3. 선택: Cloudflare Access로 그 서브도메인 자체에도 로그인을 요구하도록 설정하면 이중 방어가 됩니다.

5. 인증 설정

.env에서 아래 둘 중 하나를 선택해 채웁니다 (둘 다 설정하면 GitHub OAuth가 우선됩니다).

옵션 A — GitHub OAuth (Claude.ai 커넥터용, 권장)

Claude.ai의 "커스텀 커넥터 추가" 화면은 OAuth만 지원하고 고정 토큰 입력 칸이 없습니다. GitHub 로그인으로 게이트를 걸고, 로그인에 성공해도 본인 GitHub 계정이 아니면 도구 호출 자체를 거부하도록 서버에 이미 구현되어 있습니다.

1. https://github.com/settings/developers → OAuth Apps → New OAuth App

2. Homepage URL: 4단계에서 받은 터널 URL (예: https://xxxx.trycloudflare.com)

3. Authorization callback URL: 그 URL + /auth/callback (예: https://xxxx.trycloudflare.com/auth/callback)

4. 생성 후 Client ID 확인, Generate a new client secret 로 시크릿 발급

5. .env에 입력:

   PUBLIC_BASE_URL=https://xxxx.trycloudflare.com   # 터널 URL, 끝에 슬래시 없이
   GITHUB_OAUTH_CLIENT_ID=...
   GITHUB_OAUTH_CLIENT_SECRET=...
   GITHUB_ALLOWED_USERNAME=본인의-github-아이디

⚠️ 임시 터널(trycloudflare.com)은 cloudflared를 재시작할 때마다 URL이 바뀝니다. URL이 바뀌면 GitHub OAuth App의 Homepage/Callback URL과 .env의 PUBLIC_BASE_URL을 다시 맞춰줘야 합니다. 검증하는 동안은 cloudflared를 끄지 말고 계속 켜두세요.

옵션 B — 고정 토큰 (Claude Code CLI 등 커스텀 헤더 지원 클라이언트용)

python -c "import secrets; print(secrets.token_urlsafe(32))"

결과를 .env의 MCP_AUTH_TOKEN에 저장. 모든 요청에 Authorization: Bearer <토큰> 헤더가 필요해집니다.

아무것도 설정하지 않으면

서버가 인증 없이 열립니다. Cloudflare Access 등으로 앞단이 이미 보호되고 있을 때만 사용하세요.

6. 서버 실행

source .venv/bin/activate
set -a; source .env; set +a
python -m telegram_mcp.server

http://0.0.0.0:8811/mcp 에서 Streamable HTTP MCP 엔드포인트가 열립니다 (4단계에서 이미 열어둔 터널이 그대로 이 포트를 가리키고 있어야 합니다).

7. ChatGPT / Claude에 커넥터로 등록

• URL: https://<터널 또는 도메인>/mcp

• GitHub OAuth(옵션 A)를 설정했다면 Claude.ai 쪽 "OAuth 클라이언트 ID/시크릿" 칸은 비워둔 채 URL만 입력하고 추가하면 됩니다 — Claude가 자동으로 클라이언트를 등록하고 GitHub 로그인 화면으로 안내합니다.

• 고정 토큰(옵션 B)을 설정했다면, 헤더 설정이 가능한 클라이언트에서 Authorization: Bearer <토큰> 으로 붙이세요.

각 서비스의 "커스텀 커넥터/MCP 서버 추가" 설정 화면에서 위 URL을 입력하면 됩니다. (UI 경로는 두 서비스 모두 자주 바뀌므로, 설정 메뉴에서 "Connectors" 또는 "MCP" 항목을 찾으세요.)

보안 주의사항

• TG_SESSION_STRING, TG_API_HASH, GITHUB_OAUTH_CLIENT_SECRET, MCP_AUTH_TOKEN 은 모두 비밀값입니다. .env 밖으로 노출/커밋하지 마세요.

• GitHub OAuth 경로는 GITHUB_ALLOWED_USERNAME과 일치하는 계정으로 로그인했을 때만 도구 호출이 허용되도록 미들웨어에서 검증합니다 (src/telegram_mcp/server.py의 OwnerOnlyMiddleware). 다른 GitHub 계정은 로그인은 되어도 도구 호출 시 거부됩니다.

• 이 서버는 읽기 전용이지만, 텔레그램 계정 전체(모든 채팅)를 읽을 수 있는 자격증명을 사용하므로 유출 시 피해 범위가 큽니다. 터널 URL/토큰/시크릿을 신뢰할 수 있는 곳에만 사용하세요.