Telegram Bot Sender 사용 설명서

개요

텔레그램 채팅/채널에 텍스트, 이미지, 링크, 문서를 일방향으로 전송하는 알림 봇입니다.

---

설치 및 실행

pip install -r requirements.txt

# GUI 실행
python app.py

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

# MCP 서버 실행
python mcp_server.py

---

GUI 사용법

1. 설정

상단 설정 영역에서 Bot Token과 Chat ID를 입력합니다.

항목	설명
Bot Token	@BotFather에서 발급받은 API 토큰
Chat ID	메시지를 받을 채팅/채널 ID

설정 저장 (.env) 버튼을 누르면 .env 파일에 저장되어 다음 실행 시 자동으로 불러옵니다.

---

2. 텍스트 탭

메시지를 입력하고 전송 버튼을 눌러 텍스트 메시지를 보냅니다.

• HTML로 전송 체크박스:
  • 체크됨 (기본) — HTML 태그가 텔레그램에서 서식으로 렌더링됩니다. 예: <b>굵게</b> → 굵게
  • 해제됨 — HTML 태그가 이스케이프되어 텍스트 그대로 표시됩니다. 예: <b>굵게</b> → <b>굵게</b>

---

3. 이미지 탭

입력	설명
파일	로컬 이미지 파일 선택 (PNG, JPG, GIF, BMP, WebP)
또는 URL	인터넷 이미지 URL 직접 입력
캡션	이미지 아래에 표시될 텍스트 (선택)

파일과 URL 중 하나만 입력하면 됩니다. 파일이 우선 적용됩니다.

---

4. 링크 탭

입력	설명
제목 (버튼 텍스트)	인라인 버튼에 표시될 텍스트
URL	버튼 클릭 시 이동할 주소
설명	버튼 위에 표시될 메시지 텍스트 (선택)

링크는 일반 텍스트가 아닌 인라인 키보드 버튼으로 전송됩니다.

---

5. 문서 탭

입력	설명
파일	전송할 문서 파일 선택 (모든 형식)
캡션	문서 아래에 표시될 텍스트 (선택)

---

6. 로그

화면 하단에 전송 결과와 오류 메시지가 시간과 함께 표시됩니다.

---

텔레그램 지원 HTML 태그

"HTML로 전송" 체크 시 아래 태그를 사용할 수 있습니다.

텍스트 스타일

태그	결과	예시
<b>, <strong>	굵게	<b>텍스트</b>
<i>, <em>	기울임	<i>텍스트</i>
<u>, <ins>	밑줄	<u>텍스트</u>
<s>, <strike>, <del>	취소선	<s>텍스트</s>
<span class="tg-spoiler">	스포일러	<span class="tg-spoiler">숨김</span>

링크

<a href="https://example.com">링크 텍스트</a>

코드

태그	용도	예시
<code>	인라인 코드	<code>변수명</code>
<pre>	코드 블록	<pre>여러 줄 코드</pre>
<pre><code class="language-python">	언어별 코드 블록	구문 강조 적용

인용

<blockquote>인용문</blockquote>
<blockquote expandable>접을 수 있는 긴 인용문</blockquote>

커스텀 이모지

<tg-emoji emoji-id="5368324170671202286">👍</tg-emoji>

중첩 규칙

• <b>, <i>, <u>, <s>, 스포일러는 서로 중첩 가능
• <pre>, <code> 내부에는 다른 서식 태그 불가
• <blockquote>는 중첩 불가

주의사항

• <br> 태그는 지원되지 않음 — 줄바꿈은 텍스트에 직접 엔터로 입력
• 글꼴, 색상 변경은 지원되지 않음
• 지원되지 않는 태그 사용 시 전송 오류 발생 가능

---

CLI 사용법 (bot.py)

TelegramSender 클래스를 직접 사용하여 프로그래밍 방식으로 메시지를 전송할 수 있습니다.

import asyncio
from bot import TelegramSender

async def main():
    sender = TelegramSender()

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

    # 이미지 전송 (로컬 파일)
    await sender.send_image("./photo.jpg", caption="사진 캡션")

    # 이미지 전송 (URL)
    await sender.send_image_url("https://example.com/image.png", caption="URL 이미지")

    # 링크 전송 (인라인 버튼)
    await sender.send_link("사이트 방문", "https://example.com", description="설명 텍스트")

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

asyncio.run(main())

모든 메서드는 async이며, 전송된 Message 객체를 반환합니다.

---

MCP 서버 (AI 에이전트용)

mcp_server.py는 AI 에이전트가 텔레그램 메시지를 전송할 수 있도록 MCP 도구를 제공합니다.

제공 도구

도구	설명
send_text	HTML 텍스트 메시지 전송
send_image	로컬 이미지 파일 전송
send_image_url	URL 이미지 전송
send_link	인라인 버튼 링크 전송
send_document	문서/파일 전송

AI 클라이언트 설정

mcp_config.sample.json의 내용을 사용하는 AI 클라이언트의 설정 파일에 추가합니다.

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

클라이언트	설정 파일 위치
Claude Desktop	%APPDATA%\Claude\claude_desktop_config.json
Claude Code	프로젝트 루트 .mcp.json 또는 ~/.claude.json

환경변수는 env 필드 또는 .env 파일로 제공할 수 있습니다.

---

단일 실행파일 빌드

GUI 앱을 .exe 파일 하나로 패키징할 수 있습니다.

pip install pyinstaller

pyinstaller --onefile --noconsole --name TelegramSender ^
  --exclude-module PyQt5 --exclude-module PySide6 ^
  --exclude-module numpy --exclude-module PIL ^
  --exclude-module IPython --exclude-module pytest ^
  --exclude-module zmq --exclude-module nbformat ^
  --exclude-module jedi app.py

• 결과: dist/TelegramSender.exe
• .env 파일을 exe와 같은 폴더에 배치하거나, 실행 후 GUI에서 설정을 입력하면 됩니다.