# Telegram MCP Bridge

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

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](https://t.me/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

```bash
pip install telegram-mcp-bridge
```

Or from source:

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

### 3. Configure

```bash
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

```bash
tg-mcp-daemon
```

For macOS, use launchd for auto-start:

```bash
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
```

### 5. Register MCP in Claude Code

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

Or if installed from source:

```bash
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

```bash
# 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 (launchd)
launchctl kickstart -k gui/$(id -u)/com.claude.tg-mcp-daemon

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

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

```bash
# 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
