텔레그램 MCP 서버

• 텔레그램 MCP 서버
  • 에 대한
  • MCP란 무엇인가요?
  • 이 서버는 무슨 역할을 하나요?
  • 실제 사용 사례
  • 필수 조건
  • 설치
  • 구성
    • Telegram API 구성
    • 클로드 데스크톱 구성
    • 텔레그램 구성
  • 개발
    • 시작하기
    • 터미널에서 서버 디버깅
    • Inspector에서 서버 디버깅
  • 문제 해결
    • 'MCP 서버 mcp-telegram에 연결할 수 없습니다' 메시지

에 대한

이 서버는 Telegram API와 AI 어시스턴트를 연결하는 다리 역할을 하며 Model Context Protocol을 기반으로 합니다.

[!중요] 이 서버를 사용하기 전에 Telegram API 서비스 약관을 읽고 이해했는지 확인하십시오. Telegram API를 오용할 경우 계정이 정지될 수 있습니다.

MCP란 무엇인가요?

모델 컨텍스트 프로토콜(MCP)은 Claude Desktop과 같은 AI 앱이 외부 도구 및 데이터 소스에 연결할 수 있도록 하는 시스템입니다. AI 어시스턴트가 사용자의 제어권을 유지하면서 로컬 서비스 및 API를 사용할 수 있는 명확하고 안전한 방법을 제공합니다.

이 서버는 무슨 역할을 하나요?

현재 해당 서버는 Telegram API에 대한 읽기 전용 액세스를 제공합니다.

• [x] 대화 목록(채팅, 채널, 그룹) 가져오기
• [x] 주어진 대화 상자에서 (읽지 않은) 메시지 목록을 가져옵니다.
• [ ] 채널을 읽음으로 표시
• [ ] 날짜 및 시간별로 메시지 검색
• [ ] 미디어 파일 다운로드
• [ ] 연락처 목록을 가져옵니다
• [ ] 메시지 초안 작성
• ...

실제 사용 사례

• [x] 읽지 않은 메시지 요약을 만듭니다.
• [ ] 다가오는 생일을 가진 연락처를 찾아 인사말을 예약하세요
• [ ] 주어진 주제에 대한 토론을 찾아 요약하고 링크 목록을 제공합니다.

필수 조건

• uv 도구

설치

지엑스피1

[!NOTE] 이미 서버를 설치한 경우 uv tool upgrade --reinstall 명령을 사용하여 업데이트할 수 있습니다.

[!NOTE] 서버를 삭제하려면 uv tool uninstall mcp-telegram 명령을 사용하세요.

구성

Telegram API 구성

서버를 사용하려면 먼저 Telegram API에 연결해야 합니다.

1. Telegram API 에서 API ID와 해시를 가져옵니다.
2. 다음 명령을 실행하세요.
   mcp-telegram sign-in --api-id <your-api-id> --api-hash <your-api-hash> --phone-number <your-phone-number>
   Telegram에서 받은 코드를 입력하여 API에 연결하세요.2단계 인증이 활성화된 경우 비밀번호가 필요할 수 있습니다.

[!NOTE] Telegram API에서 로그아웃하려면 mcp-telegram logout 명령을 사용하세요.

클로드 데스크톱 구성

Claude Desktop이 Exa MCP 서버를 인식하도록 구성합니다.

1. Claude Desktop 구성 파일을 엽니다.
   • MacOS에서는 구성 파일이 ~/Library/Application Support/Claude/claude_desktop_config.json 에 있습니다.
   • Windows에서 구성 파일은 %APPDATA%\Claude\claude_desktop_config.json 에 있습니다.

   참고: Claude Desktop 앱 설정 내부에서도 claude_desktop_config.json을 찾을 수 있습니다.

2. 서버 구성 추가
   { "mcpServers": { "mcp-telegram": { "command": "mcp-server", "env": { "TELEGRAM_API_ID": "<your-api-id>", "TELEGRAM_API_HASH": "<your-api-hash>", }, } } } }

텔레그램 구성

Telegram API를 사용하기 전에 고유한 API ID와 해시를 얻어야 합니다.

1. 사용할 개발자 계정의 전화번호로 Telegram 계정에 로그인하세요.
2. API 개발 도구를 클릭하세요.
3. '새 애플리케이션 만들기' 창이 나타납니다. 애플리케이션 세부 정보를 입력하세요. URL은 입력할 필요가 없으며, 처음 두 필드(앱 제목과 짧은 이름)만 나중에 변경할 수 있습니다.
4. 마지막에 있는 '애플리케이션 만들기'를 클릭하세요. API 해시는 비밀로 유지되며 Telegram에서는 해시를 취소할 수 없습니다. 어디에도 게시하지 마세요!

개발

시작하기

1. 저장소를 복제합니다
2. 종속성을 설치하세요
   uv sync
3. 서버를 실행하세요
   uv run mcp-telegram --help

src/mcp_telegram/tools.py 파일에 도구를 추가할 수 있습니다.

새로운 도구를 추가하는 방법:

1. ToolArgs에서 상속되는 새 클래스를 만듭니다.
   class NewTool(ToolArgs): """Description of the new tool.""" pass
   클래스의 속성은 도구의 인수로 사용됩니다. 클래스 docstring은 도구 설명으로 사용됩니다.
2. 새 클래스에 대한 tool_runner 함수를 구현합니다.
   @tool_runner.register async def new_tool(args: NewTool) -> t.Sequence[TextContent | ImageContent | EmbeddedResource]: pass
   이 함수는 TextContent, ImageContent 또는 EmbeddedResource의 시퀀스를 반환해야 합니다. 이 함수는 비동기적이어야 하며 새 클래스의 단일 인수를 받아야 합니다.
3. 완료! 클라이언트를 다시 시작하면 새 도구를 사용할 수 있습니다.

검증은 Claude Desktop을 통해서나 도구를 직접 실행하여 수행할 수 있습니다.

터미널에서 서버 디버깅

도구를 직접 실행하려면 다음 명령을 사용하세요.

Inspector에서 서버 디버깅

MCP 검사기는 멋진 UI를 사용하여 서버 디버깅을 지원하는 도구입니다. 실행하려면 다음 명령을 사용하세요.

[!WARNING] 검사기에서 환경 변수 TELEGRAM_API_ID 및 TELEGRAM_API_HASH를 정의하는 것을 잊지 마세요.

문제 해결

'MCP 서버 mcp-telegram에 연결할 수 없습니다' 메시지

Claude Desktop에서 'MCP 서버 mcp-telegram에 연결할 수 없습니다'라는 메시지가 나타나면 서버 구성이 잘못되었다는 의미입니다.

다음을 시도해 보세요.

• 구성 파일에서 uv 바이너리의 전체 경로를 사용하세요.
• 구성 파일에서 복제된 저장소 경로를 확인하세요