텔레그램 MCP 서버

클로드와 같은 AI 비서가 사용자 클라이언트 API(봇 API 아님)를 사용하여 텔레그램 계정과 상호작용할 수 있도록 하는 MCP 서버입니다. @mtproto/core 와 FastMCP 프레임워크를 사용하여 구축되었습니다.

특징

도구

• listChannels

  • 서버의 캐시를 기반으로, 해당 계정에서 접근 가능한 Telegram 채널/채팅을 나열합니다.

  • 매개변수:

    • limit (숫자, 선택 사항): 반환할 최대 채널 수(기본값: 50).

  • 출력: ID, 제목, 유형 및 액세스 해시(해당되는 경우)가 포함된 채널/채팅 목록입니다.

• searchChannels

  • 이름에 키워드가 포함된 캐시된 채널/채팅을 검색합니다.

  • 매개변수:

    • keywords (문자열): 채널 이름에서 검색할 키워드입니다.

    • limit (숫자, 선택 사항): 반환할 결과의 최대 개수(기본값: 100).

  • 출력: 일치하는 채널/채팅 목록.

• getChannelMessages

  • ID를 사용하여 특정 채널/채팅의 최근 메시지를 검색합니다.

  • 매개변수:

    • channelId (숫자): 채널/채팅의 숫자 ID( listChannels 또는 searchChannels 에서 얻음).

    • limit (숫자, 선택 사항): 반환할 최대 메시지 수(기본값: 100).

    • filterPattern (문자열, 선택 사항): 텍스트 내용에 따라 메시지를 필터링하는 JavaScript 호환 정규 표현식입니다.

  • 출력: ID, 날짜, 텍스트, 발신자 ID를 포함하는 메시지 목록.

필수 조건

1. Node.js: 버전 18 이상을 권장합니다.

2. 텔레그램 계정:

   • 활성화된 Telegram 계정이 필요합니다.

   • 계정에서 2단계 인증(2FA)을 활성화해야 합니다(설정 → 개인정보 보호 및 보안 → 2단계 인증).

3. Telegram API 자격 증명:

   • https://core.telegram.org/api/obtaining_api_id 에서 새 애플리케이션을 만들어 api_id 와 api_hash 얻습니다.

설치

1. 이 저장소를 복제하세요:

   지엑스피1

2. 종속성 설치:

   npm install

구성

설정해야 할 두 가지 별도 구성이 있습니다.

1. MCP 서버 구성:

   환경 변수를 사용하여 Telegram MCP 서버를 구성합니다( .env 파일이나 사용자 환경에서 직접 구성):

   TELEGRAM_API_ID=YOUR_API_ID TELEGRAM_API_HASH=YOUR_API_HASH TELEGRAM_PHONE_NUMBER=YOUR_PHONE_NUMBER_WITH_COUNTRY_CODE # e.g., +15551234567

   플레이스홀더 값을 실제 자격 증명으로 바꾸세요.

2. MCP 클라이언트 구성:

   클라이언트 소프트웨어(Claude Desktop, Cursor 등)를 구성하여 해당 구성 파일을 수정하여 MCP 서버에 연결합니다.

   { "mcpServers": { "telegram": { "url": "http://localhost:8080/sse", "disabled": false, "timeout": 30 } } }

   Claude Desktop의 경우 구성 파일은 다음 위치에 있습니다.

   • macOS의 경우: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows의 경우: %APPDATA%/Claude/claude_desktop_config.json

   중요: 변경 사항을 적용하려면 MCP 클라이언트를 다시 시작하세요.

서버 실행

1. 최초 로그인(중요 첫 단계): 서버를 처음 실행할 때(또는 세션이 만료되거나 유효하지 않은 경우) Telegram 인증을 받아야 합니다. 터미널에서 직접 실행하세요.

   npm start

   • 서버는 .env 파일의 자격 증명을 사용합니다.

   • 터미널에서 Telegram 계정으로 전송된 로그인 코드와 필요한 경우 2FA 비밀번호를 입력하라는 메시지가 표시됩니다.

   • 로그인에 성공하면 세션 파일( ./data/session.json )이 생성됩니다. 이 파일을 통해 서버는 향후 코드/비밀번호 입력 없이 자동으로 로그인할 수 있습니다.

   • 서버는 채팅 캐시( ./data/dialog_cache.json )를 생성하거나 로드하려고 시도합니다. 특히 채팅이 많을 경우 처음 실행할 때 시간이 다소 걸릴 수 있습니다. 캐시가 있으면 이후 실행 속도가 더 빨라집니다.

2. 일반 작업: 프로젝트 디렉토리에서 npm start 실행하여 서버를 수동으로 시작해야 합니다.

   서버가 실행되면 MCP 클라이언트(예: Claude Desktop)가 구성에 지정된 URL(기본값: http://localhost:8080/sse )을 통해 서버에 연결됩니다.

문제 해결

• 로그인 프롬프트: MCP 클라이언트에서 서버를 시작할 때 로그인 코드/비밀번호를 계속 묻는 경우, data/session.json 파일이 존재하고 유효한지 확인하세요. 세션을 새로 고치려면 npm start 수동으로 한 번 실행해야 할 수도 있습니다. 또한, MCP 클라이언트를 실행하는 사용자가 data 디렉터리를 읽고 쓸 수 있도록 파일 권한이 설정되어 있는지 확인하세요.

• 캐시 문제: 채널이 오래되었거나 누락된 경우, ./data/dialog_cache.json 파일을 삭제하고 서버를 재시작하여( npm start 수동으로 실행하여) 전체 새로 고침을 강제로 진행할 수 있습니다. 이 작업에는 시간이 걸릴 수 있습니다.

• 모듈을 찾을 수 없습니다. 프로젝트 디렉터리에서 npm install 실행했는지 확인하세요. MCP 클라이언트가 서버를 시작하는 경우, 작업 디렉터리가 올바르게 설정되어 있는지 확인하거나 절대 경로를 사용하세요.

• 기타 문제: 다른 문제가 발생하면 이 서버 저장소 에서 문제를 제기해 주시기 바랍니다.

Telegram 클라이언트 라이브러리

이 저장소에는 MCP 서버에서 사용하는 기본 telegram-client.js 라이브러리도 포함되어 있습니다. 라이브러리를 직접 사용하는 방법(예: 사용자 지정 스크립팅)에 대한 자세한 내용은 LIBRARY.md 파일을 참조하세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.