본문으로 건너뛰기
시골프로그래머의 블로그
블로그 메뉴

텔레그램으로 알림을 보내는 작은 봇 — TeleBot

텔레그램 채팅이나 채널로 글, 이미지, 링크, 문서를 보내는 알림 봇입니다. 화면 프로그램, 파이썬 코드, AI 에이전트용 MCP 서버 세 가지 방법으로 씁니다.

풀빛컴퓨팅2분 읽기#오픈소스#Python#텔레그램#MCP

작업이 끝났을 때, 서버에 문제가 생겼을 때, 보고서가 만들어졌을 때 휴대폰으로 바로 알림을 받고 싶은 경우가 많습니다. 텔레그램 봇을 하나 만들어 두면 되지만, 매번 API 호출 코드를 새로 짜기는 번거롭습니다.

TeleBot은 텔레그램 채팅이나 채널로 메시지를 한 방향으로 보내기만 하는 알림 봇입니다. 받은 메시지에 답하는 기능은 없습니다. 같은 기능을 화면 프로그램, 파이썬 코드, MCP 서버 세 가지로 씁니다.

무엇을 보내나

종류 내용
텍스트 HTML 서식을 켜거나 끌 수 있음
이미지 내 PC의 파일(PNG, JPG, GIF, BMP, WebP) 또는 인터넷 주소, 캡션 선택
링크 일반 글이 아니라 인라인 버튼으로 보냄
문서 형식 상관없이 파일 하나, 캡션 선택

HTML 서식을 켜면 <b>, <i>, <u>, <s>, <code>, <pre>, <blockquote>, 스포일러 같은 텔레그램 지원 태그가 서식으로 보입니다. 끄면 태그가 글자 그대로 나갑니다.

써 보기

@BotFather에서 봇 토큰을 받고, 메시지를 받을 채팅 ID를 알아 둡니다.

pip install -r requirements.txt

# GUI 실행
python app.py

# CLI 실행 (데모)
python bot.py

# MCP 서버 실행
python mcp_server.py

화면 프로그램은 tkinter로 만들었습니다. 위쪽에 토큰과 채팅 ID를 넣고 **설정 저장 (.env)**을 누르면 다음 실행 때 자동으로 불러옵니다. 텍스트·이미지·링크·문서 탭이 있고, 아래쪽 로그 창에 전송 결과와 오류가 시간과 함께 찍힙니다.

내 프로그램에서 보내려면 bot.py의 TelegramSender 클래스를 씁니다. 메서드는 모두 async입니다.

import asyncio
from bot import TelegramSender

async def main():
    sender = TelegramSender()

    # 텍스트 전송
    await sender.send_text("<b>알림</b> 새 메시지입니다.")

    # 문서 전송
    await sender.send_document("./report.pdf", caption="보고서")

asyncio.run(main())

AI 에이전트에서 쓰기

mcp_server.py를 등록하면 Claude Desktop이나 Claude Code 같은 에이전트가 대화 중에 텔레그램으로 결과를 보냅니다. 도구는 send_text, send_image, send_image_url, send_link, send_document 다섯 가지입니다.

{
  "mcpServers": {
    "telegram-sender": {
      "command": "python",
      "args": ["C:/path/to/TeleBot/mcp_server.py"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here",
        "TELEGRAM_CHAT_ID": "your-chat-id-here"
      }
    }
  }
}

args의 경로는 내 PC에서 mcp_server.py가 있는 위치로 바꿉니다. 토큰과 채팅 ID는 env 대신 .env 파일로 넘겨도 됩니다.

알아 둘 점

  • 텔레그램 HTML은 <br>을 지원하지 않습니다. 줄바꿈은 글에 직접 넣습니다. 지원하지 않는 태그를 쓰면 전송 오류가 날 수 있습니다.
  • 화면 프로그램은 PyInstaller로 실행 파일 하나(dist/TelegramSender.exe)로 묶을 수 있습니다.
  • 의존 패키지는 python-telegram-bot, python-dotenv, mcp입니다. 라이선스는 MIT입니다.

소스와 사용 설명은 GitHub 저장소에 있습니다.

함께 읽으면 좋은 글