MCP 텔레그램

MCP(Model Context Protocol)를 통해 대규모 언어 모델을 Telegram에 연결합니다.

Telethon 으로 구축된 이 서버는 AI 에이전트가 Telegram과 상호 작용할 수 있도록 하여 MTProto를 사용하여 메시지 보내기/편집/삭제, 채팅 검색, 초안 관리, 미디어 다운로드 등의 기능을 사용할 수 있도록 합니다.

🚀 시작하기

필수 조건

Python 3.10 이상
uv 공식 uv 가이드를 통해 설치하세요.

설치

mcp-telegram CLI 도구를 설치하세요:

지엑스피1

⚙️ 사용법

[!중요] 이 도구를 사용하기 전에 Telegram의 서비스 약관을 읽고 이해했는지 확인하십시오. 이 도구를 잘못 사용하면 계정이 제한될 수 있습니다.

mcp-telegram 명령줄 도구는 여러분의 진입점입니다.

mcp-telegram --help # See all commands

MCP 서버에 연결

Claude Desktop이나 Cursor와 같은 MCP 클라이언트에서 MCP Telegram을 사용하려면 MCP 서버를 구성해야 합니다. 구성 과정은 클라이언트와 운영 체제에 따라 다릅니다.

자세한 설정 지침은 다음을 참조하세요.

구성 파일에는 다음이 포함되어야 합니다.

{
  "mcpServers": {
    "mcp-telegram": {
      "command": "mcp-telegram" /* Use full path if client can't find the command (e.g. "/usr/local/bin/mcp-telegram"). See IMPORTANT section below for full path instructions. */,
      "args": ["start"],
      "env": {
        "API_ID": "<your_api_id>",
        "API_HASH": "<your_api_hash>"
      }
    }
  }
}

[!참고] 구성 경로는 OS 및 클라이언트에 따라 다릅니다. 예:
macOS: ~/Library/Application Support/Claude/ 또는 ~/.cursor/
Windows: %APPDATA%\Claude\ 또는 %APPDATA%\Cursor\

[!중요] 클라이언트가 터미널에서 mcp-telegram 실행할 수 있는데도 실행할 수 없는 경우, 실행 파일의 전체 경로를 입력해 보세요. 터미널에서 which mcp-telegram (macOS/Linux) 또는 where mcp-telegram (Windows)을 실행하여 전체 경로를 찾을 수 있습니다. 설정 파일의 command 값을 전체 경로로 바꾸세요.

구성 파일을 저장한 후 애플리케이션을 다시 시작합니다.

🧰 사용 가능한 도구

MCP를 통해 Telegram과 상호 작용하는 데 사용할 수 있는 도구의 포괄적인 목록은 다음과 같습니다.

📨 메시징 도구

도구	설명
`send_message`	✉️ 모든 사용자, 그룹 또는 채널에 문자 메시지나 파일을 보냅니다.
`edit_message`	✏️ 이전에 보낸 메시지의 내용을 수정하세요
`delete_message`	🗑️ 하나 또는 여러 개의 메시지를 제거하세요
`get_messages`	📜 고급 필터링 옵션을 사용하여 메시지 기록 검색

🔍 검색 및 탐색

도구	설명
`search_dialogs`	🔎 이름이나 사용자 이름으로 사용자, 그룹 및 채널 찾기
`message_from_link`	🔗 Telegram 링크를 사용하여 특정 메시지에 액세스하세요

📝 초안 관리

도구	설명
`get_draft`	📋 모든 채팅의 현재 메시지 초안 보기
`set_draft`	✍️ 메시지 초안 만들기 또는 지우기

📂 미디어 처리

도구	설명
`media_download`	📸 메시지에서 사진, 비디오 및 문서를 다운로드하세요

[!참고] 자세한 매개변수 정보 및 예제 사용 사례를 보려면 터미널에서 mcp-telegram tools 실행하세요.

🛠️ 문제 해결

데이터베이스 잠금 오류

동일한 세션 파일을 사용하여 여러 mcp-telegram 인스턴스를 실행하면 Telethon의 SQLite 세션 저장소로 인해 database is locked 오류가 발생할 수 있습니다. 한 번에 하나의 인스턴스만 세션 파일을 사용하도록 하세요.

잠재적으로 중단된 프로세스를 중지해야 하는 경우:

macOS / Linux: pkill -f "mcp-telegram"
Windows: taskkill /F /IM mcp-telegram.exe /T (정확한 프로세스 이름은 작업 관리자에서 확인하세요)

🤝 기여하기

여러분의 참여를 환영합니다! MCP 텔레그램 개선에 도움을 주시고 싶으시다면, 이슈, 기능 요청 또는 풀 리퀘스트를 자유롭게 제출해 주세요. 여러분의 피드백과 기여는 모두에게 더 나은 프로젝트를 만드는 데 큰 도움이 됩니다.

📝 라이센스

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

MCP Telegram