telegram-mcp

mtcute를 사용하여 Telegram과 상호작용하기 위한 MCP(Model Context Protocol) 서버입니다.

기능

• 채팅으로 텍스트 메시지 전송

• 특정 채팅에서 들어오는 메시지 대기

• 채팅에서 메시지 읽기

• 메시지 검색

• 대화(채팅) 목록 나열 및 정보 가져오기

• 모든 채팅의 최근 메시지 가져오기

• 계정 및 채널의 이모지 상태 ID 설정 및 확인

Related MCP server: io.github.daedalus/mcp-telegram-bot

설정

설치

옵션 1: 사전 빌드된 바이너리 다운로드

릴리스 페이지에서 플랫폼에 맞는 최신 릴리스를 다운로드하세요:

• macOS (Apple Silicon): telegram-mcp-darwin-arm64.tar.gz

• macOS (Intel): telegram-mcp-darwin-x64.tar.gz

• Linux: telegram-mcp-linux-x64.tar.gz

• Windows: telegram-mcp-win-x64.exe.zip

아카이브를 추출하고 바이너리를 실행 가능하게 만드세요(Unix 시스템):

tar -xzf telegram-mcp-*.tar.gz
chmod +x telegram-mcp

옵션 2: 소스에서 빌드

1. 저장소를 복제하고 종속성을 설치합니다:

   git clone git@github.com:zhigang1992/telegram-mcp.git
   cd telegram-mcp
   bun install

2. 실행 파일을 빌드합니다:

   bun run build

초기 설정 (최초 1회만)

1. https://my.telegram.org 에서 Telegram API 자격 증명을 받으세요.

2. 초기 설정을 실행하여 Telegram에 인증합니다:

   export API_ID=your_api_id
   export API_HASH=your_api_hash
   ./telegram-mcp

   서버는 다음을 수행합니다:

   • 전화번호 입력을 요청합니다.

   • Telegram을 통해 인증 코드를 보냅니다.

   • 인증 코드를 요청합니다.

   • 절대 저장 경로를 표시합니다(MCP 구성에 필요합니다).

3. 출력에 표시된 저장 경로를 기록해 두세요. 다음과 같은 형태입니다:

   Storage path: /Users/username/telegram-mcp/bot-data/session

사용법

MCP 서버로 사용

초기 설정에서 얻은 저장 경로를 사용하여 Claude Desktop 구성에 추가하세요:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/telegram-mcp",
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash",
        "TELEGRAM_STORAGE_PATH": "/absolute/path/from/initial/setup"
      }
    }
  }
}

중요: TELEGRAM_STORAGE_PATH는 초기 설정 중에 표시된 절대 경로여야 합니다. 이렇게 해야 MCP 서버가 인증된 세션을 사용할 수 있습니다.

사용 가능한 도구

메시지 도구

• messages_sendText - 채팅으로 텍스트 메시지 전송

  • chatId (필수): 채팅/사용자 ID 또는 사용자 이름

  • text (필수): 보낼 메시지 텍스트

  • replyToMessageId: 답장할 메시지 ID (선택 사항)

• messages_getHistory - 채팅에서 메시지 기록 가져오기

  • chatId (필수): 채팅/사용자 ID 또는 사용자 이름

  • limit: 메시지 수 (기본값: 100, 최대: 100)

  • offsetId: 페이지 매김을 위한 메시지 ID

• messages_search - 메시지 검색

  • query (필수): 검색 쿼리

  • chatId: 검색할 특정 채팅 (선택 사항)

  • limit: 결과 수 (기본값: 50)

• messages_getRecent - 모든 채팅에서 최근 메시지 가져오기

  • limit: 채팅 수 (기본값: 10)

  • messagesPerChat: 채팅당 메시지 수 (기본값: 10)

대화형 도구

• wait_for_reply - 채팅에서 다음 메시지 대기

  • chatId (필수): 메시지를 기다릴 채팅/사용자 ID 또는 사용자 이름

  • timeoutSeconds: 초 단위 타임아웃 (기본값: 60, 최대: 300)

상태 도구

• status_getCurrent - 피어의 현재 이모지 상태 가져오기

  • peerId: 대상 피어, 기본값은 self

• status_setEmoji - 이모지 상태 설정 또는 해제

  • peerId: 대상 피어, 기본값은 self

  • emojiId: 사용자 지정 이모지 문서 ID, clear=true가 아닌 경우 필수

  • isCollectible: emojiId가 수집 가능한 ID인 경우 true로 설정

  • until: ISO-8601 타임스탬프 또는 Unix 타임스탬프 문자열 (선택 사항)

  • clear: 상태를 설정하는 대신 현재 상태 해제

• status_listAvailable - 사용 가능한 기본 이모지 상태 ID 나열

  • scope: self 또는 channel (기본값: self)

  • limit: 반환할 최대 ID 수 (기본값: 100)

• status_listCollectibles - 자체 이모지 상태로 사용할 수 있는 소유한 수집 가능한 ID 나열

  • owner: 확인할 피어, 기본값은 self

  • limit: 반환할 최대 수집품 수 (기본값: 100)

대화 도구

• dialogs_list - 모든 대화 나열

  • limit: 최대 대화 수 (기본값: 50)

  • filter: 필터 옵션 (onlyUsers, onlyGroups, onlyChannels)

• dialogs_getInfo - 상세 대화 정보 가져오기

  • chatId (필수): 채팅/사용자 ID 또는 사용자 이름

개발

개발 모드에서 실행:

bun run dev

서버는 세션 데이터를 bot-data/ 디렉토리에 저장합니다.