mcp-telegram

Claude와 같은 AI 어시스턴트를 사용자 API(MTProto)를 통해 실제 텔레그램 계정에 연결하는 MCP 서버입니다. 봇이 아니며, Claude가 사용자 대신 메시지를 읽고 보냅니다.

gotd/td와 공식 MCP Go SDK로 구축되었습니다.

텔레그램 API 서비스 약관: 이 프로젝트는 텔레그램 사용자 API를 사용합니다. my.telegram.org에서 직접 api_id와 api_hash를 발급받아야 하며, 텔레그램 API 서비스 약관을 준수해야 합니다. 사용자 API를 오용(스팸, 대량 메시지 발송, 스크래핑 등)할 경우 계정이 정지될 수 있습니다. 이 도구의 사용에 대한 모든 책임은 사용자 본인에게 있습니다.

목차

• 기능

• 활용 방법

• chaindead/telegram-mcp와의 비교

• 빠른 시작

• 클라이언트 설정

• 설정 참조

• 보안

기능

추가 기능:

• 파일 및 사진 전송

• 채팅 간 메시지 전달

• 특정 메시지에 대한 답장

• 메시지 기록에서 사진 및 문서 다운로드

• 날짜 범위별 기록 필터링 (since / until)

• ID 충돌 방지를 위한 타입 지정 피어 참조 (user:ID, chat:ID, channel:ID)

• 지연 피어 해석(Lazy peer resolution) — 시작 시 FLOOD_WAIT 오류 방지

• RPC 수준의 전역 속도 제한

활용 방법

연결 후 AI 어시스턴트에게 다음과 같이 요청할 수 있습니다:

메시지 확인

• "읽지 않은 텔레그램 메시지를 확인하고 요약해 줘"

• "지난 24시간 동안 @alice가 보낸 메시지는 뭐야?"

• "월요일 이후 Dev Team 채팅에서 온 메시지를 보여줘"

답장 및 소통

• "@bob의 마지막 메시지에 대한 답장을 초안으로 작성해 줘 (아직 보내지 마)"

• "@alice에게 '좋아요, 오후 3시에 만나요'라고 보내줘"

• "프로젝트 채팅의 1234번 메시지에 내 피드백을 답장으로 보내줘"

받은 편지함 관리

• "뉴스 채널의 모든 메시지를 읽음 처리해 줘"

• "화이트리스트에 있는 채팅 중 읽지 않은 메시지가 있는 곳은 어디야?"

• "디자인 채팅의 오늘 메시지에 포함된 사진들을 다운로드해 줘"

조사 및 분석

• "지난주 배포와 관련된 모든 메시지를 찾아줘"

• "어제 팀 채팅에서 나눈 논의 내용을 요약해 줘"

• "이번 달 프로젝트 채널에서 공유된 파일은 무엇이야?"

chaindead/telegram-mcp와의 비교

빠른 시작

사전 요구 사항

• Go 1.26+

• 텔레그램 계정

• my.telegram.org에서 발급받은 API 자격 증명 (api_id 및 api_hash)

설치

Homebrew (macOS / Linux):

brew install Prgebish/tap/mcp-telegram

사전 빌드된 바이너리 (macOS / Linux / Windows):

GitHub Releases에서 다운로드하세요.

Go 설치:

go install github.com/Prgebish/mcp-telegram/cmd/mcp-telegram@latest

소스에서 빌드:

git clone https://github.com/Prgebish/mcp-telegram.git
cd mcp-telegram
go build ./cmd/mcp-telegram

이 명령은 현재 디렉토리에 mcp-telegram(Windows의 경우 mcp-telegram.exe)을 생성합니다.

인증

인증 명령을 한 번 실행하여 세션 파일을 생성합니다. 전화번호, 로그인 코드, (설정된 경우) 2단계 인증 비밀번호를 입력하라는 메시지가 표시됩니다.

macOS / Linux:

export TG_APP_ID=12345
export TG_API_HASH="your_api_hash"

mcp-telegram auth --config config.yaml

Windows (PowerShell):

$env:TG_APP_ID = "12345"
$env:TG_API_HASH = "your_api_hash"

mcp-telegram.exe auth --config config.yaml

Windows (cmd):

set TG_APP_ID=12345
set TG_API_HASH=your_api_hash

mcp-telegram.exe auth --config config.yaml

설정

config.yaml 파일을 생성합니다:

telegram:
  app_id: ${TG_APP_ID}
  api_hash: ${TG_API_HASH}
  session_path: ~/.config/mcp-telegram/session.json

acl:
  chats:
    - match: "@username"
      permissions: [read, draft, mark_read]
    - match: "user:123456789"
      permissions: [read, send]
    - match: "channel:2225853048"
      permissions: [read, mark_read]

limits:
  max_messages_per_request: 50
  max_dialogs_per_request: 100
  rate:
    requests_per_second: 2.0
    burst: 3

logging:
  level: info

${...} 구문의 환경 변수는 로드 시점에 확장됩니다.

클라이언트 설정

서버는 stdio를 통해 통신하며, MCP 클라이언트가 프로세스를 시작하고 관리합니다.

Claude Code (CLI — 명령어로 추가):

claude mcp add telegram -- /path/to/mcp-telegram serve --config /path/to/config.yaml

Claude Desktop / Claude Code (~/.claude.json 또는 claude_desktop_config.json):

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/mcp-telegram",
      "args": ["serve", "--config", "/path/to/config.yaml"],
      "env": {
        "TG_APP_ID": "12345",
        "TG_API_HASH": "your_api_hash"
      }
    }
  }
}

Cursor (설정 > MCP Servers > 추가):

{
  "telegram": {
    "command": "/path/to/mcp-telegram",
    "args": ["serve", "--config", "/path/to/config.yaml"],
    "env": {
      "TG_APP_ID": "12345",
      "TG_API_HASH": "your_api_hash"
    }
  }
}

설정

ACL

ACL은 기본 거부(default-deny) 방식입니다. acl.chats에 명시적으로 나열된 채팅만 지정된 권한으로 접근할 수 있습니다.

지원되는 매칭 패턴:

권한 유형: read, send, draft, mark_read.

동일한 피어가 여러 규칙(예: @username 및 user:ID)에 매칭되는 경우 권한이 병합되며, 서로 덮어쓰지 않습니다.

속도 제한

limits.rate 섹션은 모든 텔레그램 RPC 호출을 감싸는 전역 토큰 버킷을 설정합니다:

• requests_per_second — 지속적인 속도 (기본값: 2.0)

• burst — 최대 버스트 크기 (기본값: 3)

미디어 다운로드

media:
  download: [photo, document, video, voice, audio]
  directory: ~/telegram-media
  allowed_upload_dirs:
    - ~/Documents
    - ~/Downloads

설정 시 tg_history는 미디어 파일을 지정된 디렉토리로 자동으로 다운로드합니다. download_to 매개변수로 경로를 재정의할 수 있지만, media.directory 또는 그 하위 디렉토리로만 가능합니다.

allowed_upload_dirs는 tg_send가 파일을 읽을 수 있는 디렉토리를 제한합니다. 이 설정이 없으면 파일 전송 기능이 비활성화됩니다.

보안

• 기본 거부 ACL — 명시적으로 화이트리스트에 추가되지 않은 채팅은 접근 불가

• 파일 시스템 경계 — tg_send는 allowed_upload_dirs에 있는 파일만 읽을 수 있으며, download_to는 media.directory의 하위 디렉토리로 제한됨

• 세션 파일 권한 — 0600(소유자만 읽기/쓰기 가능)으로 강제됨

• 비밀 정보 로깅 금지 — API 해시, 세션 토큰, 인증 키는 로그에 기록되지 않음

• 액세스 해시 노출 방지 — 내부 텔레그램 액세스 해시는 모든 도구 출력에서 제거됨

• 속도 제한 — 의도치 않은 API 남용 방지

• 로컬 시간대 — 날짜 필터는 UTC가 아닌 시스템 시간대를 사용함

라이선스

MIT

이 프로젝트가 유용했다면 별표를 눌러주세요. 다른 사람들이 프로젝트를 발견하는 데 큰 도움이 됩니다.