Compose and post formatted content to a Telegram channel -- MarkdownV2 escaping, message splitting, media ordering
Add this skill
npx mdskills install n24q02m/channel-postComprehensive Telegram channel posting workflow with detailed MarkdownV2 escaping rules and media handling
mcp-name: io.github.n24q02m/better-telegram-mcp
MCP server for Telegram with dual-mode support: Bot API (httpx) for quick bot integrations and MTProto (Telethon) for full user-account access.
message, chat, media, contact, config, helpreadOnlyHint, destructiveHint, idempotentHint, openWorldHinttelegram://docs/* resourcesVia marketplace (includes skills: /setup-bot, /channel-post):
/plugin marketplace add n24q02m/claude-plugins
/plugin install better-telegram-mcp@n24q02m-plugins
Set credentials in ~/.claude/settings.local.json or shell profile. See Environment Variables.
Add to ~/.codex/config.toml:
[mcp_servers.better-telegram-mcp]
command = "uvx"
args = ["--python", "3.13", "better-telegram-mcp"]
Python 3.13 required -- Python 3.14+ is not supported.
/newbot, follow prompts to name your bot123456789:ABCdefGHI-JKLmnoPQRstUVwxyz)api_id (integer) and api_hash (32-char hex string){
"mcpServers": {
"telegram": {
"command": "uvx",
"args": ["--python", "3.13", "better-telegram-mcp"]
}
}
}
Other MCP clients (Cursor, Codex)
// Cursor (~/.cursor/mcp.json), Windsurf, Cline, Amp, OpenCode
{
"mcpServers": {
"telegram": {
"command": "uvx",
"args": ["--python", "3.13", "better-telegram-mcp"]
}
}
}
# Codex (~/.codex/config.toml)
[mcp_servers.telegram]
command = "uvx"
args = ["--python", "3.13", "better-telegram-mcp"]
{
"mcpServers": {
"telegram": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "TELEGRAM_BOT_TOKEN",
"-v", "telegram-data:/data",
"n24q02m/better-telegram-mcp"
]
}
}
}
Configure credentials in ~/.claude/settings.local.json or your shell profile. See Environment Variables below.
For user mode in Docker, mount the session directory with
-v ~/.better-telegram-mcp:/dataso the session persists across container restarts.
| Tool | Actions | Description |
|---|---|---|
message | send, edit, delete, forward, pin, react, search, history | Send, edit, delete, forward messages. Pin, react, search, browse history |
chat | list, info, create, join, leave, members, admin, settings, topics | List and manage chats, groups, channels. Members, admin, forum topics |
media | send_photo, send_file, send_voice, send_video, download | Send photos, files, voice notes, videos. Download media from messages |
contact | list, search, add, block | List, search, add contacts. Block/unblock users (user mode only) |
config | status, set, cache_clear | Server status, update runtime settings, clear cache |
help | -- | Full documentation for any topic |
| URI | Content |
|---|---|
telegram://docs/messages | Message operations reference |
telegram://docs/chats | Chat management reference |
telegram://docs/media | Media send/download reference |
telegram://docs/contacts | Contact management reference |
telegram://stats | All documentation combined |
No environment variables needed. On first start, the server opens a setup page in your browser:
uvx, or Docker)Your credentials never leave your machine. The relay server only sees encrypted data.
For CI/automation, you can still use environment variables (see below).
| Variable | Required | Default | Description |
|---|---|---|---|
TELEGRAM_BOT_TOKEN | Bot mode | -- | Bot token from @BotFather |
TELEGRAM_API_ID | User mode | -- | API ID from my.telegram.org (integer) |
TELEGRAM_API_HASH | User mode | -- | API hash from my.telegram.org (32-char hex) |
TELEGRAM_PHONE | User mode | -- | Phone number with country code (e.g., +84912345678) |
TELEGRAM_AUTH_URL | No | https://better-telegram-mcp.n24q02m.com | Auth relay URL. Set local for localhost-only mode |
TELEGRAM_SESSION_NAME | No | default | Session file name (useful for multiple accounts) |
TELEGRAM_DATA_DIR | No | ~/.better-telegram-mcp | Data directory for session files |
Mode detection: If TELEGRAM_API_ID + TELEGRAM_API_HASH are set, user mode is used. Otherwise, TELEGRAM_BOT_TOKEN is used. No silent fallback -- if neither is set, the server exits with an error.
| Feature | Bot | User |
|---|---|---|
| Send/Edit/Delete/Forward messages | Y | Y |
| Pin messages, React | Y | Y |
| Search messages, Browse history | -- | Y |
| List chats, Create groups/channels | -- | Y |
| Get chat info, Manage members | Y | Y |
| Send media (photo/file/voice/video) | Y | Y |
| Download media | -- | Y |
| Contacts (list/search/add/block) | -- | Y |
~/.better-telegram-mcp/.session (600 permissions)| Auth Mode | TELEGRAM_AUTH_URL | Use case |
|---|---|---|
| Remote (default) | https://better-telegram-mcp.n24q02m.com | Headless, SSH, Docker |
| Self-hosted | https://your-domain.com | Custom relay deployment |
| Local | local | Desktop, offline |
Headless auth (Docker/SSH) -- use curl against the auth URL shown in logs:
curl -X POST http://127.0.0.1:PORT/send-code
curl -X POST http://127.0.0.1:PORT/verify -d '{"code":"12345"}'
curl -X POST http://127.0.0.1:PORT/verify -d '{"password":"your-2fa-password"}' # if 2FA
git clone https://github.com/n24q02m/better-telegram-mcp.git
cd better-telegram-mcp
uv sync
uv run better-telegram-mcp
MIT -- See LICENSE.
Install via CLI
npx mdskills install n24q02m/channel-postChannel Post is a free, open-source AI agent skill. Compose and post formatted content to a Telegram channel -- MarkdownV2 escaping, message splitting, media ordering
Install Channel Post with a single command:
npx mdskills install n24q02m/channel-postThis downloads the skill files into your project and your AI agent picks them up automatically.
Channel Post works with Claude Code, Claude Desktop, Cursor, Vscode Copilot, Windsurf, Continue Dev, Gemini Cli, Amp, Roo Code, Goose. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.