Provides tools for sending messages, photos, documents, keyboards, invoices, and managing bot commands and callbacks via the Telegram Bot API, designed to work alongside Claude Channels without polling conflicts.
Provides tools for interacting with the TON blockchain, including balance checks, token transfers, NFT queries, DEX swap estimates, staking info, and wallet connection flows via TonKeeper.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@claude-channels-telegram-mcp send the generated chart as a photo to the Telegram chat"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The missing outbound layer for Claude Channels. Adds photos, files (PDFs, source code), keyboards, Telegram Stars, and TON tools to Claude Code — safely coexisting with Channels via CHANNELS_MODE (no polling conflicts).
Claude Channels handles inbound Telegram messages and provides reply, react, and edit_message for outbound. That's it. Any richer response — a photo, a file, a button, a payment invoice — requires this toolkit.
Example: Claude Code coding session, results delivered to Telegram
Claude does | Tool |
Generates a chart or graph |
|
Edits a source file |
|
Produces a test result report (PDF) |
|
Takes a screenshot during web testing |
|
Claude Channels built-in | This toolkit adds |
|
|
|
|
|
|
(inbound handled automatically) |
|
— | 16 TON blockchain tools incl. TON Connect |
Other Bot API MCP servers (TONresistor/telegram-mcp, tsgram-mcp, ton-agent-kit) also provide outbound tools — but they all poll getUpdates continuously. Running them alongside Claude Channels causes offset conflicts: messages get dropped or delivered twice.
CHANNELS_MODE=true disables all polling in this toolkit. Channels owns the inbound; this toolkit handles the outbound. No conflicts.
CHANNELS_MODE (CHANNELS_MODE=true) — the intended use case, alongside Claude Channels:
Inbound: handled by Channels automatically
Outbound: all 30 send/TON tools available
Polling disabled — no offset conflicts with Channels
Standalone (no Channels) — also supported, without the Channels plugin:
Inbound: get_updates / get_pending_messages available
All 33 tools available
Related MCP server: tsgram-mcp
Tool | Description |
| Send plain text (HTML) messages; supports reply-to for threaded replies |
| Send messages with inline keyboard buttons (URL links or callbacks) |
| Register |
| Set bot profile description |
| Send photos (URL or local file) with caption |
| Send documents/files with caption |
| Delete bot's own messages |
| Pin a message in chat |
| Get chat/user information |
| Send Telegram Stars payment invoice |
| Show "typing…" / "sending photo…" status in chat |
| Get download URL for a file from its |
| Respond to inline button presses with toast/alert; closes loading spinner |
| Approve or reject a Telegram Stars payment (10 s deadline) |
| Fetch incoming messages/callbacks via polling (standalone mode only) |
| Simplified view of unread messages (standalone mode only) |
| Advance internal offset to mark updates as processed (standalone mode only) |
Tool | Description |
| Get TON balance for any wallet address |
| Get all token (Jetton) holdings |
| Real-time token price + 24h/7d change |
| DEX swap output estimation |
| Execute TON transfer from agent wallet (requires wallet config) |
| Generate |
| Fetch recent TON/Jetton transaction history for any address |
| Send Jetton tokens (e.g. USDT) from agent wallet (requires wallet config) |
| List NFT items owned by a wallet (name, image, collection) |
| Get NFT collection metadata (name, description, item count, owner) |
| Resolve a |
| List top liquid staking pools (APY, TVL, min stake) sorted by APY |
| Generate TonKeeper connection link (returns session_id + URL button) |
| Poll session for wallet connection status and address |
| Request TON payment from connected user wallet (user approves in TonKeeper) |
| Disconnect wallet and delete session |
git clone https://github.com/Masashi-Ono0611/claude-channels-telegram-mcp.git
cd claude-channels-telegram-mcp && bun installAdd to your project's .mcp.json:
{
"mcpServers": {
"telegram-toolkit": {
"command": "bun",
"args": ["run", "/path/to/claude-channels-telegram-mcp/src/index.ts"],
"env": {
"TELEGRAM_BOT_TOKEN": "<your-bot-token>",
"TON_API_BASE_URL": "https://testnet.tonapi.io",
"CHANNELS_MODE": "true"
}
}
}
}Mode | When to use | Tools |
CHANNELS_MODE (recommended) | With Claude Channels plugin | 30 tools (polling excluded) |
Standalone | Without Claude Channels | 33 tools (polling included) |
Set CHANNELS_MODE=true in your .mcp.json env (shown above — already included in the example).
# Required
TELEGRAM_BOT_TOKEN=<bot-token-from-botfather>
CHANNELS_MODE=true # set to true when using alongside Claude Channels plugin
# TON network (auto-detects testnet/mainnet from URL)
TON_API_BASE_URL=https://testnet.tonapi.io # testnet (default)
TON_API_BASE_URL=https://tonapi.io # mainnet
TON_API_KEY=<optional-api-key> # increases rate limits
# Agent wallet (required for send_ton / transfer_jetton)
AGENT_MNEMONIC_PATH=/path/to/mnemonic.txt
TONCENTER_ENDPOINT=<override-if-needed> # auto-derived from TON_API_BASE_URL
TONCENTER_API_KEY=<optional-toncenter-key>If TON env vars are not set, TON tools return "not configured" errors. Telegram tools work regardless.
Claude Code
│
├── Claude Channels (built-in plugin)
│ └── reply, react, edit_message (inbound + outbound messaging)
│
└── claude-channels-telegram-mcp (this MCP server)
├── Telegram: send, keyboards, media, commands, invoice, callbacks, polling
└── TON: balance, price, swap, transfer, payment links, tx history, jetton, wallet connectKey design: In CHANNELS_MODE, only send-only APIs are active — no polling conflicts with Channels. In standalone mode, get_updates + send_message + answer_callback_query provide a full receive-respond loop. TON read tools use tonapi.io; write tools use TonCenter RPC. Network (testnet/mainnet) is auto-detected from TON_API_BASE_URL.
User presses inline button → get_updates → callback_query received
→ answer_callback_query("Processing...") → send_invoice(Stars)
→ User pays → pre_checkout_query received
→ answer_pre_checkout_query(ok=true) → send_message("Payment complete!")generate_ton_payment_link + send_keyboard enables a user-pays flow without exposing the agent wallet:
Claude → generate_ton_payment_link → send_keyboard with URL button
User taps button → TonKeeper / any TON wallet opens → user signs & sends
Claude → get_transactions → verify payment receivedgenerate_tonconnect_link + send_keyboard connects a user's own wallet (TonKeeper) without exposing any agent private key:
Claude → generate_tonconnect_link → { session_id, tonkeeper_link }
Claude → send_keyboard with URL button (tonkeeper_link)
User taps → TonKeeper opens → user approves connection
Claude → check_tonconnect_session(session_id) → { status: "connected", address }
Claude → request_ton_payment(session_id, to, "0.5") → user approves in TonKeeper → { boc }
Claude → disconnect_wallet(session_id)Session state is persisted to ~/.ctt/sessions/<session_id>.json, so connection survives across MCP calls.
In CHANNELS_MODE (CHANNELS_MODE=true), the three polling tools are disabled at both ListTools and CallTool level to prevent offset conflicts with the Channels plugin.
⚠️ reply vs send_message — not interchangeable
Channels | toolkit | |
Responds in conversation thread | ✅ | ❌ (sends a new standalone message) |
Requires chat_id | ❌ (implicit) | ✅ (must provide) |
Available in CHANNELS_MODE | ✅ | ✅ |
Use Channels reply for all conversational responses. Use send_message only for proactive or scheduled sends (e.g. notifications).
⚠️ Callback buttons don't work in CHANNELS_MODE
Callback buttons (callback_data) require get_updates to receive the callback event back from Telegram. Since polling is disabled in CHANNELS_MODE, the callback data is never delivered to Claude.
Button type | CHANNELS_MODE | Standalone |
URL button ( | ✅ works | ✅ works |
Callback button ( | ❌ data never arrives | ✅ works |
In CHANNELS_MODE, use URL buttons for all interactive elements (payment links, TonKeeper connect, external pages).
Tool | Result |
| ✅ 5 commands registered |
| ✅ Description set |
| ✅ URL buttons sent |
| ✅ URL image sent |
| ✅ Local file sent |
| ✅ Message deleted |
| ✅ Message pinned |
| ✅ User info retrieved |
| ✅ 1 Star invoice sent |
| ✅ 4.76 TON |
| ✅ $1.26 (+2.65%) |
| ✅ Jetton holdings listed |
| ✅ Swap estimate returned |
| ✅ TON transfer confirmed |
| ✅ ton:// + TonKeeper links generated |
| ✅ Tx history fetched |
| ✅ Jetton transfer confirmed |
| ✅ "typing…" status shown |
| ✅ Download URL returned |
| ✅ Incoming messages fetched |
| ✅ Unread messages listed |
| ✅ Offset advanced |
| ✅ Plain text + reply_to tested |
| ✅ Toast (show_alert=false) tested |
| ✅ Validation guard + 1 Star payment approved |
| ✅ count=0 (testnet wallet, API reachable) |
| ✅ "Hipo Payout" collection fetched |
| ✅ foundation.ton resolved |
| ✅ 5 pools returned |
| ✅ TonKeeper link generated |
| ✅ connected + address (testnet, real device) |
| ✅ 0.01 TON signed + BOC returned (testnet) |
| ✅ session disconnected + file deleted |
MIT
This server cannot be deployed
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
Manage Telegram drafts, media, schedules and publications from AI clients.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Run a Telegram channel from your AI agent. Posts go out through your own bot, not your account.