mcp-telegram

텔레그램용 MCP 서버 — AI 어시스턴트가 텔레그램 계정과 상호작용하도록 지원

기능

• 채팅 관리: 채팅 목록 조회, 검색, 음소거/음소거 해제

• 메시지: 메시지 읽기, 검색, 컨텍스트 검사, 전송, 초안 작성, 예약, 링크 확인 및 백업

• AI 요약: 여러 LLM 제공자를 사용하여 채팅 대화 요약

• 보안: 세션은 macOS 키체인에 저장됨 (Linux/Windows는 파일 기반 저장)

설치

go install github.com/tolmachov/mcp-telegram@latest

또는 소스에서 빌드:

git clone https://github.com/tolmachov/mcp-telegram.git
cd mcp-telegram
make

설정

1. 텔레그램 API 자격 증명 받기

1. my.telegram.org/apps로 이동

2. 애플리케이션 생성

3. api_id와 api_hash 복사

2. 환경 구성

자격 증명 저장 (macOS 키체인; Linux/Windows의 경우 ~/.local/state/mcp-telegram/config.json에 0600 권한으로 일반 텍스트 JSON 저장):

mcp-telegram config set TELEGRAM_API_ID 123456789
mcp-telegram config set TELEGRAM_API_HASH abcd1234efgh5678

또는 .env 파일 사용:

cp .env.example .env
# Edit .env with your credentials

3. 텔레그램 로그인

mcp-telegram login --phone +1234567890

텔레그램으로 전송된 인증 코드를 입력하라는 메시지가 표시됩니다.

4. MCP 클라이언트 구성

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows)에 추가:

{
  "mcpServers": {
    "telegram": {
      "command": "mcp-telegram",
      "args": ["run"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash"
      }
    }
  }
}

Claude Code

claude mcp add telegram -- /path/to/mcp-telegram run

.env 파일에 환경 변수를 설정하거나 --env를 통해 전달하세요.

사용 가능한 도구

MCP 클라이언트에 19개의 도구가 노출됩니다. 메시지는 불투명한 문자열 핸들("42"는 일반 메시지, "s:42"는 예약 메시지)로 식별됩니다. 도구 출력에서 그대로 복사하여 후속 호출에 사용하세요. 절대 수동으로 파싱하거나 생성하지 마십시오.

사용 가능한 리소스

고정된 채팅 리소스는 각 고정된 채팅에 대해 동적으로 생성되고 백그라운드에서 새로 고쳐집니다. 세트가 변경되면 클라이언트는 resources/list_changed를 수신합니다.

사용 가능한 프롬프트

MCP 클라이언트가 슬래시 명령어나 빠른 작업으로 노출하는 3개의 매개변수화된 프롬프트입니다.

프롬프트 예시

AI 어시스턴트와 함께 사용할 수 있는 몇 가지 프롬프트 예시입니다:

메시지 관리

• "텔레그램에서 읽지 않은 중요한 메시지가 있는지 확인해줘"

• "읽지 않은 모든 텔레그램 메시지를 요약해줘"

• "읽지 않은 메시지를 읽고 분석해서 필요한 경우 답장 초안을 작성해줘"

• "중요하지 않은 읽지 않은 메시지를 확인하고 간단히 개요를 알려줘"

• "지난주 업무 채팅에서 '송장'이 언급된 메시지를 찾아줘"

• "이 텔레그램 링크 주변의 컨텍스트를 열어줘: https://t.me/example/123"

정리

• "내 텔레그램 대화를 분석해서 폴더 구조를 제안해줘"

• "텔레그램 채팅을 중요도별로 분류하는 것을 도와줘"

• "업무 관련 대화를 모두 찾아서 정리 방법을 제안해줘"

커뮤니케이션

• "[주제]에 대한 업데이트를 특정 채팅에서 모니터링해줘"

• "[채팅]의 마지막 메시지에 대한 정중한 답장을 작성해줘"

• "채팅 중에 답변되지 않은 질문이 있는지 확인해줘"

• "이 텔레그램 메시지 링크를 확인하고 스레드 컨텍스트를 보여줘"

백업 및 내보내기

• "[연락처]와의 대화를 파일로 백업해줘"

• "[그룹]의 지난주 메시지를 내보내줘"

• "미디어 전용 업데이트도 백업해서 누락되는 것이 없도록 해줘"

채팅 요약

SummarizeChat 도구는 여러 LLM 제공자를 지원합니다:

• sampling (실험적): MCP Sampling을 통해 MCP 클라이언트의 LLM을 사용합니다. 샘플링을 지원하는 클라이언트(VS Code, fast-agent, Continue)에서만 작동합니다. Claude Desktop이나 Claude Code에서는 작동하지 않습니다.

• ollama: Ollama를 통한 로컬 LLM - API 키 불필요

• gemini: Google Gemini API

• anthropic: Anthropic Claude API

환경 변수를 통해 구성하세요:

SUMMARIZE_PROVIDER=ollama  # or: sampling, gemini, anthropic
SUMMARIZE_MODEL=           # provider-specific model name

명령어

# Run MCP server (used by MCP clients)
mcp-telegram run

# Login to Telegram
mcp-telegram login --phone +1234567890

# Logout and delete session
mcp-telegram logout

# Securely store config values (macOS Keychain / file on Linux)
mcp-telegram config set TELEGRAM_API_ID 123456789
mcp-telegram config set TELEGRAM_API_HASH abcd1234

# List stored keys
mcp-telegram config list

# Delete a stored value
mcp-telegram config delete TELEGRAM_API_ID

허용된 키: TELEGRAM_API_ID, TELEGRAM_API_HASH, ANTHROPIC_API_KEY, GEMINI_API_KEY.

구성 옵션

파괴적 작업

DeleteMessage와 같은 도구는 진행하기 전에 MCP elicitation을 통해 사용자 확인을 요청합니다. MCP 클라이언트가 elicitation을 지원하지 않는 경우, 서버는 파괴적인 작업을 실행하기 전에 LLM의 지침에 따라 구두로 확인을 받습니다.

세션 저장

• macOS: 키체인에 안전하게 저장됨.

• Linux/Windows: 0600 파일 권한으로 ~/.local/state/mcp-telegram/session.json에 저장됨. 이 파일은 일반 텍스트이므로 포함된 사용자 계정을 신뢰하고, 민감한 계정을 다룰 때는 macOS에서 실행하는 것을 권장합니다.

mcp-telegram config set을 통해 설정된 구성 값(API 키, 텔레그램 자격 증명)은 동일한 백엔드를 따릅니다: macOS는 키체인, Linux/Windows는 일반 텍스트 JSON.

라이선스

MIT