telegram-mcp-bridge 0.1.3

Telegram MCP bridge for Claude Code — daemon + stdio proxy with multi-session support

Telegram MCP Bridge

Telegram MCP bridge for Claude Code — get notifications, ask questions, and interact with your Claude Code sessions through Telegram.

Each Claude Code session gets its own thread (topic) in a Telegram group, so you can monitor multiple sessions at once.

Features

• Send messages — progress updates, final reports, notifications
• Ask and wait — ask questions in Telegram and get answers back in Claude Code
• Inline buttons — present options for the user to choose from
• Send files — share screenshots, logs, documents
• Real-time monitoring — watch for incoming Telegram messages
• Multi-session — each Claude Code session gets its own Telegram thread

Architecture

Telegram group (is_forum: true, with Topics)
  └── Thread per session ("{project} #{pid} — {time}")
        │
  daemon.py  (single process, launchd, port 8765)
  aiohttp HTTP API + single Telegram long-polling via httpx
        │
  proxy.py  (stdio MCP, spawned by Claude Code)
  Thin FastMCP proxy: lazy registration on first tool call
        │
  Claude Code (any number of sessions)

Why two processes? Telegram Bot API allows only one getUpdates polling per token. The daemon centralizes polling and distributes messages to sessions via HTTP.

Quick Start

1. Create a Telegram bot and group

1. Create a bot via @BotFather — save the token
2. Create a Telegram group, enable Topics (group settings → Topics)
3. Add the bot to the group as admin (needs "Manage Topics" permission)
4. Get the group chat ID (send a message, then check https://api.telegram.org/bot<TOKEN>/getUpdates)

2. Install

pip install telegram-mcp-bridge

Or from source:

git clone https://github.com/OlegPrivet/telegram-mcp-bridge.git
cd telegram-mcp-bridge
pip install -e .

3. Configure

mkdir -p ~/.claude/channels/telegram-daemon
cat > ~/.claude/channels/telegram-daemon/.env << EOF
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_CHAT_ID=-100your-group-id
DAEMON_PORT=8765
EOF

4. Start the daemon

tg-mcp-daemon

For macOS, use launchd for auto-start:

cd telegram-mcp-bridge
./launchd/generate-plist.sh
cp launchd/com.claude.tg-mcp-daemon.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude.tg-mcp-daemon.plist

For Windows, use Task Scheduler for auto-start:

# Create a scheduled task that starts the daemon at logon
schtasks /create /tn "TelegramMCPDaemon" /tr "tg-mcp-daemon" /sc onlogon /rl limited

# Or if installed from source:
schtasks /create /tn "TelegramMCPDaemon" /tr "python -m telegram_mcp_bridge.daemon" /sc onlogon /rl limited

# Start it now without rebooting
schtasks /run /tn "TelegramMCPDaemon"

Note (Windows): The config directory is %USERPROFILE%\.claude\channels\telegram-daemon\.env. Create it with:

mkdir "$env:USERPROFILE\.claude\channels\telegram-daemon" -Force
@"
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_CHAT_ID=-100your-group-id
DAEMON_PORT=8765
"@ | Set-Content "$env:USERPROFILE\.claude\channels\telegram-daemon\.env"

5. Register MCP in Claude Code

claude mcp add telegram -s user -- tg-mcp-proxy

Or if installed from source:

claude mcp add telegram -s user -- python3 -m telegram_mcp_bridge.proxy

MCP Tools

Tool	Description
send_message(message)	Send a message (fire-and-forget)
send_file(file_path, caption?)	Send a file/screenshot to the thread
send_and_wait(message)	Send and wait for a reply (5 min timeout)
send_and_wait_with_options(message, options)	Send with inline buttons
monitor_chat()	Wait for incoming message (30 min timeout)
check_inbox()	Check for unread messages (non-blocking)
list_sessions()	List active sessions

Management

Daemon

# Health check
curl -s http://127.0.0.1:8765/api/health

# Active sessions
curl -s http://127.0.0.1:8765/api/sessions | python3 -m json.tool

# Restart (macOS launchd)
launchctl kickstart -k gui/$(id -u)/com.claude.tg-mcp-daemon

# Stop (macOS launchd)
launchctl bootout gui/$(id -u)/com.claude.tg-mcp-daemon

# Restart (Windows Task Scheduler)
schtasks /end /tn "TelegramMCPDaemon" & schtasks /run /tn "TelegramMCPDaemon"

# Stop (Windows Task Scheduler)
schtasks /end /tn "TelegramMCPDaemon"

# Delete scheduled task (Windows)
schtasks /delete /tn "TelegramMCPDaemon" /f

# Logs
tail -f ~/.claude/channels/telegram-daemon/daemon.log

Proxy

Proxy processes are spawned automatically by Claude Code — one per session. They unregister gracefully on exit.

# Proxy logs
tail -f /tmp/tg_mcp_proxy.log

Configuration

Variable	Default	Description
TELEGRAM_BOT_TOKEN	—	Bot token from @BotFather (required)
TELEGRAM_CHAT_ID	—	Group chat ID with topics (required)
DAEMON_PORT	8765	HTTP API port for daemon
SESSION_NAME	auto	Custom session name for the thread

License

MIT