local-only server

The server can only run on the client’s local machine because it depends on local resources.

Integrations

Allows Claude to access a Telegram account to read chats, view messages, send messages, mark messages as read, and retrieve conversation context to formulate natural-sounding replies.

텔레그램 MCP 서버

이것은 클로드가 귀하의 Telegram 계정에 접근하여 메시지를 읽고 보낼 수 있도록 해주는 간단한 MCP 서버입니다.

기능

get_chats : Telegram 채팅 목록을 가져옵니다
send_message : 채팅방에 메시지 보내기
get_message : 채팅에서 메시지를 가져와 읽지 않은 메시지를 인쇄합니다.
mark_messages_read : 메시지를 읽음으로 표시
get_conversation_context : 20개의 메시지를 가져와서 convostyle.txt 읽어 적절한 답변을 결정합니다.

설정

1단계: Telegram API 자격 증명 가져오기

https://my.telegram.org/apps 로 이동하세요
로그인하고 애플리케이션을 생성하세요(또는 기존 애플리케이션을 사용하세요)
API ID 와 API 해시를 기록해 두세요.

2단계: Python 환경 설정

필요한 패키지를 설치하세요:

지엑스피1

가상 환경을 설정하세요. 가능하다면 pip3 대신 사용하세요.

# Set up virtual environment
pip install uv mcp
uv venv
source .venv/bin/activate
# .venv\Scripts\activate for windows
uv add "mcp[cli]" telethon python-dotenv nest_asyncio

3단계: ID 추가

Mac(bash)의 경우:

가상 환경에서 다음을 실행합니다.

export TELEGRAM_PHONE=phone number with country code and no spaces
export TELEGRAM_API_ID=api_id
export TELEGRAM_API_HASH=api_hash

터미널에서 printenv 로 내보내졌는지 확인하세요.

Windows(PowerShell)의 경우:

가상 환경에서 다음을 실행하세요. 따옴표를 꼭 포함해야 합니다. 그렇지 않으면 PowerShell이 제대로 작동하지 않을 수 있습니다.

$env:TELEGRAM_PHONE="phone number with country code and no spaces"
$env:TELEGRAM_API_ID="api_id"
$env:TELEGRAM_API_HASH="api_hash"

PowerShell에서 gci env: 로 내보내졌는지 확인하세요.

4단계: 인증 실행

인증하려면 이 명령을 실행하세요. 2FA를 사용하는 경우 비밀번호를 입력할 때 터미널에 아무 텍스트도 표시되지 않습니다. 이는 정상입니다! 2FA 과정에서 오타를 내지 않도록 주의하세요. 오타가 발생하면 전체 프로세스가 다시 시작됩니다. 설치된 버전에 따라 python 또는 python3 사용하세요.

cd src/mcp_telegram
python3 telethon_auth.py

다음 사항을 요청드립니다.

귀하의 전화번호 (국제 형식으로 + 포함) (공백을 남기지 마십시오)
Telegram이 귀하의 계정으로 보내는 코드
2FA 비밀번호(활성화된 경우)

이렇게 하면 홈 디렉토리에 세션 파일이 생성되므로 다시 인증할 필요가 없습니다.

5단계: Claude Desktop에 추가

Claude Desktop 구성을 편집하세요.

macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
윈도우 : %APPDATA%\Claude\claude_desktop_config.json

또는 설정으로 가서 개발자 모드를 클릭한 다음 구성 편집을 클릭하세요. 개발자 모드가 활성화되어 있는지 확인하세요.

이것을 구성에 추가하세요(실제 자격 증명으로 바꾸세요):

"mcpServers": {
      "telegram": {
      "command": "/your/path/to/python3",
      "args": ["/full/path/to/mcp-telegram/main.py"],
      "env": {
          "TELEGRAM_API_ID": "your_api_id_here",
          "TELEGRAM_API_HASH": "your_api_hash_here",
          "TELEGRAM_PHONE": "+65945678900"
          }
      }
  }

main.py: 전체 경로를 얻으려면 IDE나 데스크톱으로 가서 파일을 찾은 다음 마우스 오른쪽 버튼을 클릭하고 "경로 복사"를 클릭하세요.

python: 터미널에서 where.exe python (Windows) 또는 where python (Mac)을 실행하여 전체 경로를 확인하세요(필요한 경우 python3 으로 변경). Windows를 사용하는 경우 JSON 형식 때문에 경로의 백슬래시를 슬래시로 변경해야 할 수 있습니다(ctrl+f "\", ctrl+h 모두 "/"로 변경).

매우 중요:

Python과 main.py 스크립트 모두에 대한 전체 절대 경로를 사용하세요.
API 자격 증명을 1단계의 실제 값으로 바꾸세요.
전화번호를 국제 형식으로 설정하세요

6단계(선택 사항):

챗봇이 당신의 말과 비슷하게 반응하길 원한다면 src/mcp_telegram 에 있는 convostyle.txt 자유롭게 설정하세요.

바로 그것입니다!

Claude Desktop을 다시 시작하고(종료한 후 다시 열면) 이제 Claude에게 다음 작업을 요청할 수 있습니다.

최근 Telegram 채팅을 보여주세요
특정 채팅의 메시지 읽기
특정 메시지를 "읽음"으로 표시
자연스러운 음성으로 연락처나 그룹에 메시지를 보내세요

클로드에게 메시지를 보낼 때 "텔레그램"이라는 단어를 꼭 포함하세요. 그렇지 않으면 텔레그램이 이해하지 못할 수 있습니다. 예를 들어, "클로드, 읽지 않은 텔레그램 메시지가 있나요?"와 같이 질문할 수 있습니다.

성가신 문제 해결

가상 환경에서 다음을 실행해보세요.

ls -la ~/.mcp_telegram_*

그런 다음 세션 파일을 종료합니다(파일 경로를 앞에 rm을 붙여 복사하여 붙여넣기만 하면 됩니다).

rm /Users/username/.mcp_telegram_numberininternationalformat*

3단계를 다시 시도해 보세요.

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

클로드가 귀하의 Telegram 계정에 접근하여 귀하를 대신하여 메시지를 읽고 보낼 수 있는 간단한 MCP 서버입니다.

Telegram MCP Server