Skip to main content
Glama
civilian7

telegram-sender

by civilian7

Telegram Bot Sender 사용 설명서

개요

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


Related MCP server: Telegram Channel MCP Server

설치 및 실행

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에서 설정을 입력하면 됩니다.

Related MCP Connectors

Related MCP Servers