claude-channels-telegram-mcp

claude-channels-telegram-mcp

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).

What This Is

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 | send_photo → image in Telegram | | Edits a source file | send_document → file delivered to Telegram | | Produces a test result report (PDF) | send_document → PDF in Telegram | | Takes a screenshot during web testing | send_photo → screenshot in Telegram |

| Claude Channels built-in | This toolkit adds | |---|---| | reply — plain text response | send_keyboard — inline buttons (URL or callback) | | react — emoji reaction | send_photo, send_document — media | | edit_message — edit sent message | send_invoice — Telegram Stars payment | | (inbound handled automatically) | register_commands, set_bot_description — BotFather setup | | — | 16 TON blockchain tools incl. TON Connect |

Why not just use any Bot API MCP?

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.

Primary mode: CHANNELS_MODE

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

MCP Tools — 30 in CHANNELS_MODE / 33 standalone

Telegram (17 tools)

| Tool | Description | |------|-------------| | send_message | Send plain text (HTML) messages; supports reply-to for threaded replies | | send_keyboard | Send messages with inline keyboard buttons (URL links or callbacks) | | register_commands | Register /commands in BotFather bot menu | | set_bot_description | Set bot profile description | | send_photo | Send photos (URL or local file) with caption | | send_document | Send documents/files with caption | | delete_message | Delete bot's own messages | | pin_message | Pin a message in chat | | get_chat_info | Get chat/user information | | send_invoice | Send Telegram Stars payment invoice | | send_chat_action | Show "typing…" / "sending photo…" status in chat | | get_file | Get download URL for a file from its file_id | | answer_callback_query | Respond to inline button presses with toast/alert; closes loading spinner | | answer_pre_checkout_query | Approve or reject a Telegram Stars payment (10 s deadline) | | get_updates | Fetch incoming messages/callbacks via polling (standalone mode only) | | get_pending_messages | Simplified view of unread messages (standalone mode only) | | mark_messages_read | Advance internal offset to mark updates as processed (standalone mode only) |

TON Blockchain (16 tools)

| Tool | Description | |------|-------------| | get_ton_balance | Get TON balance for any wallet address | | get_jetton_balances | Get all token (Jetton) holdings | | get_token_price | Real-time token price + 24h/7d change | | estimate_swap | DEX swap output estimation | | send_ton | Execute TON transfer from agent wallet (requires wallet config) | | generate_ton_payment_link | Generate ton:// + TonKeeper deep link — lets users pay from their own wallet | | get_transactions | Fetch recent TON/Jetton transaction history for any address | | transfer_jetton | Send Jetton tokens (e.g. USDT) from agent wallet (requires wallet config) | | get_nft_items | List NFT items owned by a wallet (name, image, collection) | | get_nft_collection | Get NFT collection metadata (name, description, item count, owner) | | resolve_ton_dns | Resolve a .ton or .t.me domain to a wallet address | | get_staking_info | List top liquid staking pools (APY, TVL, min stake) sorted by APY | | generate_tonconnect_link | Generate TonKeeper connection link (returns session_id + URL button) | | check_tonconnect_session | Poll session for wallet connection status and address | | request_ton_payment | Request TON payment from connected user wallet (user approves in TonKeeper) | | disconnect_wallet | Disconnect wallet and delete session |

Quick Start

git clone https://github.com/Masashi-Ono0611/claude-channels-telegram-mcp.git
cd claude-channels-telegram-mcp && bun install

Configure MCP

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

Operating Modes

| 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).

Environment Variables

# 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.

Architecture

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 connect

Key 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.

Complete Response Pipeline (standalone)

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!")

Payment Link Flow (CHANNELS_MODE or standalone)

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 received

TON Connect Flow (user wallet)

generate_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.

CHANNELS_MODE: What Works and What Doesn't

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 reply | toolkit send_message | |---|---|---| | 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 (url field) — opens a link | ✅ works | ✅ works | | Callback button (callback_data) — returns data to bot | ❌ data never arrives | ✅ works |

In CHANNELS_MODE, use URL buttons for all interactive elements (payment links, TonKeeper connect, external pages).

Tested

| Tool | Result | |------|--------| | register_commands | ✅ 5 commands registered | | set_bot_description | ✅ Description set | | send_keyboard | ✅ URL buttons sent | | send_photo | ✅ URL image sent | | send_document | ✅ Local file sent | | delete_message | ✅ Message deleted | | pin_message | ✅ Message pinned | | get_chat_info | ✅ User info retrieved | | send_invoice | ✅ 1 Star invoice sent | | get_ton_balance | ✅ 4.76 TON | | get_token_price | ✅ $1.26 (+2.65%) | | get_jetton_balances | ✅ Jetton holdings listed | | estimate_swap | ✅ Swap estimate returned | | send_ton | ✅ TON transfer confirmed | | generate_ton_payment_link | ✅ ton:// + TonKeeper links generated | | get_transactions | ✅ Tx history fetched | | transfer_jetton | ✅ Jetton transfer confirmed | | send_chat_action | ✅ "typing…" status shown | | get_file | ✅ Download URL returned | | get_updates | ✅ Incoming messages fetched | | get_pending_messages | ✅ Unread messages listed | | mark_messages_read | ✅ Offset advanced | | send_message | ✅ Plain text + reply_to tested | | answer_callback_query | ✅ Toast (show_alert=false) tested | | answer_pre_checkout_query | ✅ Validation guard + 1 Star payment approved | | get_nft_items | ✅ count=0 (testnet wallet, API reachable) | | get_nft_collection | ✅ "Hipo Payout" collection fetched | | resolve_ton_dns | ✅ foundation.ton resolved | | get_staking_info | ✅ 5 pools returned | | generate_tonconnect_link | ✅ TonKeeper link generated | | check_tonconnect_session | ✅ connected + address (testnet, real device) | | request_ton_payment | ✅ 0.01 TON signed + BOC returned (testnet) | | disconnect_wallet | ✅ session disconnected + file deleted |

License

MIT