telegram-channel-mcp-server

MCP server (stdio) for publishing and managing posts in a Telegram channel via the Bot API.Lets an agent (Claude Code, Claude Desktop, etc.) post text, photos, videos, albums, documents,voice messages, video notes, polls/quizzes and paid content, and edit/delete/pin posts.

Installation

npm install
npm run build

Configuration

Variable	Required	Description
`TELEGRAM_BOT_TOKEN`	yes	Bot token from @BotFather. The bot must be a channel admin with the "Post messages" permission (and the matching rights for editing/deleting).
`TELEGRAM_CHAT_ID`	no	Default channel: `-100…` or `@username`. Every tool accepts a `chat_id` that overrides the default.

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" }
    }
  }
}

Tools

Tool	What it does
`telegram_send_message`	Text with HTML/MarkdownV2, link preview control, buttons
`telegram_send_photo` / `_video` / `_animation` / `_document` / `_audio` / `_voice` / `_video_note`	A single media item with caption, spoiler, buttons
`telegram_send_media_group`	Album of 2-10 items as one post
`telegram_send_paid_media`	Paid post for Telegram Stars
`telegram_send_poll` / `telegram_stop_poll`	Poll or quiz / close it and get the results
`telegram_edit_message`	Change text, caption, media, buttons
`telegram_delete_messages`	Delete up to 100 posts
`telegram_pin_message` / `telegram_unpin_message`	Pin / unpin
`telegram_copy_message`	Copy or forward a post from another chat
`telegram_set_reaction`	React on behalf of the channel
`telegram_get_chat`	Channel info and subscriber count (read-only)

Media in every tool is given as a string: a public http(s) URL, an absolute path to a local file (the server uploads it), or a Telegram file_id (returned in the send result, so you can reuse a file without uploading it again).

Buttons are an array of rows: [[{ "text": "Website", "url": "https://…", "style": "primary" }], [{ "text": "Copy", "copy_text": "PROMO" }]]. Exactly one of url / callback_data / copy_text; style: primary | success | danger.

Bot API limitations handled by the server

Albums and video notes cannot carry buttons - send them in a separate message.
In an album show_caption_above_media applies to all items at once.
Paid content works in channels only, 1-10 000 stars.
Polls in channels are always anonymous.
Limits: text 4096 chars, caption 1024, file 50 MB on upload / 20 MB via URL.

Development

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

Layout: src/telegram.ts - API client and media resolution, src/schemas.ts - shared zod schemas,src/format.ts - response formatting, src/tools/* - tools grouped by domain, src/index.ts - entry point.

telegram-channel-mcp-server