Installation

Prerequisites

• Bun runtime
• A Telegram Bot Token from BotFather
• Claude Code CLI installed globally

Clone the project

git clone https://github.com/reysamysam/tg-claude-bridge.git
cd tg-claude-bridge

Install dependencies

# Install root dependencies
bun install

# Build the MCP server (required before root build)
cd mcp-server && bun install && bun run build && cd ..

# Type-check everything
bun run build

Create your bot

1. Open Telegram and chat with BotFather.
2. Send /newbot and follow the prompts to get your bot token.
3. Optionally set a bot username via /setname and description via /setdescription.

Configure environment

Create a .env file in the project root:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
WHITELIST=111222333,444555666

• TELEGRAM_BOT_TOKEN — your bot token from BotFather (required)
• WHITELIST — comma-separated Telegram user IDs who are allowed to use the bot (required)

See Environment Variables for all available options.

Run the bot

# Development (hot reload with bun)
bun --watch src/index.ts

# Production
bun start

The bot will log the sessions directory and start long-polling. Send /start to your bot to begin.

Updating

git pull
cd mcp-server && bun install && bun run build && cd ..
bun run build
bun start

Uninstalling

# Stop the bot
pkill -f "bun.*index.ts"

# Remove sessions and workspace data
rm -rf ./sessions

# Remove dependencies
rm -rf node_modules mcp-server/node_modules