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

Related MCP server: Telegram Bot MCP Server

Configuration

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

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.