Telegram MCP Server

Telegram Bot API를 통해 Telegram과 상호작용하는 MCP 서버입니다. 이 서버는 LLM 클라이언트에 메시지 전송, 최근 수신 가능한 메시지 읽기, 채팅 정보 조회를 위한 도구 세트를 제공합니다.

기능

서버는 세 가지 MCP 도구를 제공합니다:

• send_message — 지정된 Telegram 채팅에 텍스트 메시지를 전송합니다.

• get_recent_messages — 지정된 채팅에서 최근 수신 가능한 메시지를 가져옵니다.

• get_chat_info — Telegram 채팅의 기본 정보를 반환합니다.

서버는 stdio 전송을 사용하므로 별도의 HTTP 서버 없이 MCP Inspector 및 기타 MCP 클라이언트에 연결할 수 있습니다.

Related MCP server: agent-telegram-mcp

아키텍처

MCP client / MCP Inspector
            │
            │ MCP over stdio
            ▼
      src/server.py
            │
            ▼
   src/telegram_client.py
            │
            │ HTTPS
            ▼
    Telegram Bot API

server.py는 MCP 인터페이스와 도구 등록을 담당합니다.

telegram_client.py는 Telegram Bot API와의 HTTP 상호작용을 캡슐화합니다.

config.py는 환경 변수에서 토큰을 로드합니다.

기술 스택

• Python 3.10+

• MCP Python SDK 2.x

• Telegram Bot API

• httpx

• python-dotenv

프로젝트 구조

telegram-mcp/
├── src/
│   ├── __init__.py
│   ├── config.py
│   ├── telegram_client.py
│   └── server.py
├── .env.example
├── .gitignore
├── requirements.txt
└── README.md

요구 사항

• Python 3.10 이상

• @BotFather를 통해 생성된 Telegram 봇

• Node.js 및 npx — mcp dev를 통해 MCP Inspector를 사용하는 경우에만 필요

설치

저장소를 클론하고 해당 디렉토리로 이동합니다:

git clone <repository-url>
cd telegram-mcp

가상 환경을 생성합니다:

python3 -m venv .venv
source .venv/bin/activate

의존성을 설치합니다:

pip install -r requirements.txt

Telegram 봇 설정

1. Telegram을 열고 @BotFather를 찾습니다.

2. /newbot 명령을 실행합니다.

3. 봇을 생성하고 Bot API 토큰을 받습니다.

4. 토큰을 소스 코드나 Git에 추가하지 마세요.

.env 파일을 생성합니다:

cp .env.example .env

토큰을 입력합니다:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

.env는 .gitignore에 추가되어 있습니다.

채팅 준비

개인 채팅

1. 생성한 봇을 엽니다.

2. Start를 누르거나 봇에게 메시지를 보냅니다.

3. get_recent_messages를 테스트하려면 몇 개의 텍스트 메시지를 보냅니다.

그룹

1. 테스트 그룹을 생성합니다.

2. 그룹에 봇을 추가합니다.

3. 봇이 그룹의 일반 메시지를 볼 수 있게 하려면 @BotFather에서 개인 정보 보호 모드를 비활성화합니다 (/setprivacy → Disable).

4. 그룹에 몇 개의 메시지를 보냅니다.

chat_id를 얻으려면 봇이 해당 채팅에서 메시지를 수신한 후 get_chat_info 또는 get_recent_messages를 호출하는 것이 편리합니다.

실행

프로젝트 루트 디렉토리에서:

python src/server.py

서버는 stdio를 통해 작동하며 MCP 연결을 기다립니다. 따라서 실행 후 터미널에 일반적인 출력이 없는 것은 정상적인 동작입니다.

개발 및 테스트를 위해 MCP CLI를 사용할 수 있습니다:

mcp dev src/server.py

이 명령은 서버와 MCP Inspector를 실행합니다. Inspector는 npx를 사용하므로 Node.js가 PATH에 있어야 합니다.

MCP 도구

send_message

Telegram에 텍스트 메시지를 전송합니다.

매개변수:

chat_id: string — ID чата
text: string — текст сообщения

예시:

chat_id: 123456789
text: Привет! Сообщение отправлено через MCP.

서버는 전송 확인과 message_id를 반환합니다.

get_recent_messages

지정된 채팅의 최근 수신 가능한 메시지를 가져옵니다.

매개변수:

chat_id: string — ID чата
limit: integer — количество сообщений, по умолчанию 10

limit는 1에서 100 사이의 값으로 제한됩니다.

예시:

chat_id: 123456789
limit: 10

결과에는 각 수신 가능한 메시지의 발신자와 텍스트가 포함됩니다.

get_chat_info

채팅의 기본 정보를 가져옵니다.

매개변수:

chat_id: string — ID чата

응답에는 ID, 유형, 이름, 사용자 이름, 이름 및 성을 포함한 사용 가능한 필드가 표시됩니다.

메시지 수신 방식

Telegram Bot API는 봇에게 채팅 기록을 임의로 읽을 수 있는 별도의 메서드를 제공하지 않습니다. 수신 메시지를 얻기 위해 서버는 getUpdates를 사용합니다.

get_recent_messages는 최대 100개의 최근 업데이트를 요청한 후 chat_id로 필터링합니다. 따라서 이 도구는 Telegram이 업데이트 큐를 통해 봇에게 제공하는 메시지로 작동하며, 전체 채팅 기록이 아닙니다.

즉, 이 도구는 전체 대화 기록에 접근할 수 있는 Telegram 클라이언트를 대체하지 않습니다. 테스트를 위해서는 봇을 채팅에 추가한 후 메시지를 보내고 get_recent_messages를 호출하면 충분합니다.

중요: getUpdates는 활성화된 웹훅과 동시에 사용할 수 없습니다. 봇에 웹훅이 설정되어 있다면 먼저 제거해야 getUpdates를 통한 롱 폴링이 업데이트를 수신할 수 있습니다.

예제 시나리오

1. MCP Inspector를 실행합니다.

2. src/server.py를 연결합니다.

3. 다음 도구를 사용할 수 있는지 확인합니다:

   • send_message

   • get_recent_messages

   • get_chat_info

4. get_chat_info를 호출하여 채팅 연결을 확인합니다.

5. send_message를 호출하고 Telegram에 메시지가 나타나는지 확인합니다.

6. Telegram에 몇 개의 메시지를 보냅니다.

7. get_recent_messages를 호출하고 수신된 메시지 목록을 확인합니다.

보안

Telegram Bot API 토큰은 TELEGRAM_BOT_TOKEN 환경 변수를 통해서만 전달됩니다.

실제 .env 파일은 Git에 포함되어서는 안 됩니다. 저장소에는 작동하는 토큰 없이 .env.example만 보관됩니다.

제한 사항

• 봇은 Bot API를 통해 Telegram 채팅의 전체 기록에 접근할 수 없습니다.

• get_recent_messages는 사용 가능한 봇 업데이트로 작동합니다.

• 그룹에서 봇이 수신하는 메시지 세트는 Telegram의 개인 정보 보호 설정에 따라 달라집니다.

• getUpdates와 웹훅은 업데이트를 수신하는 상호 배타적인 방법입니다.