telegram-channel-mcp-server

Bot API를 통해 텔레그램 채널에 게시물을 발행하고 관리하는 MCP 서버(stdio)입니다. 에이전트(Claude Code, Claude Desktop 등)가 텍스트, 사진, 동영상, 앨범, 문서, 음성 메시지, 비디오 메모, 설문/퀴즈 및 유료 콘텐츠를 게시하고, 게시물을 편집/삭제/고정할 수 있습니다.

설치

npm install
npm run build

Related MCP server: Telegram Bot MCP Server

구성

Claude Code

claude mcp add telegram-channel -e TELEGRAM_BOT_TOKEN=123:ABC -e TELEGRAM_CHAT_ID=-1001234567890 -- node /abs/path/telegram-channel-mcp/dist/index.js

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "telegram-channel": {
      "command": "node",
      "args": ["/abs/path/telegram-channel-mcp/dist/index.js"],
      "env": { "TELEGRAM_BOT_TOKEN": "123:ABC", "TELEGRAM_CHAT_ID": "-1001234567890" }
    }
  }
}

도구

미디어는 모든 도구에서 문자열로 제공됩니다: 공개 http(s) URL, 로컬 파일의 절대 경로(서버가 업로드), 또는 텔레그램 file_id(전송 결과에 반환되므로 파일을 다시 업로드하지 않고 재사용할 수 있습니다).

버튼은 행 배열입니다: [[{ "text": "Website", "url": "https://…", "style": "primary" }], [{ "text": "Copy", "copy_text": "PROMO" }]]. url / callback_data / copy_text 중 정확히 하나만 사용하며, style: primary | success | danger입니다.

Bot API 제한 사항 처리

• 앨범과 비디오 메모에는 버튼을 넣을 수 없습니다 - 별도의 메시지로 보내세요.

• 앨범에서 show_caption_above_media는 모든 항목에 일괄 적용됩니다.

• 유료 콘텐츠는 채널에서만 사용할 수 있으며, 1~10,000 스타즈입니다.

• 채널의 설문은 항상 익명입니다.

• 제한: 텍스트 4096자, 캡션 1024자, 파일 업로드 50MB / URL 20MB.

개발

npm run dev                        # run from sources
npm run smoke -- /path/to/img.png  # e2e check against a real channel (creates and deletes test posts)
npx @modelcontextprotocol/inspector node dist/index.js

레이아웃: src/telegram.ts - API 클라이언트 및 미디어 해석, src/schemas.ts - 공유 zod 스키마, src/format.ts - 응답 형식화, src/tools/* - 도메인별 도구 그룹, src/index.ts - 진입점.