tg-cc-sync-bot-mcp

Telegram Bot MCP Server for Claude Code. Bridges Claude Code sessions and Telegram via forum topics.

Claude Code sends messages to Telegram forum topics and polls for replies — enabling async human oversight of long-running agent sessions.

Пошаговая настройка

Шаг 1: Создание бота в BotFather

1. Открыть @BotFather в Telegram
2. Отправить /newbot
3. Ввести отображаемое имя бота (например: Люда)
4. Ввести username — должен заканчиваться на _bot (например: LLuda_bot)
5. BotFather пришлёт API токен — длинная строка вида 1234567890:AAH.... Скопировать и сохранить.

Рекомендация: отключить Group Privacy, чтобы бот видел все сообщения в группе (не только ответы на него):

• В BotFather: /mybots → выбрать бота → Bot Settings → Group Privacy → Turn off

Шаг 2: Создание супергруппы с топиками

1. Создать новую группу в Telegram (обычную — она станет супергруппой автоматически)
2. Дать название (например: Claude Code PRO)
3. Зайти в настройки группы → Edit → Group Type → оставить Private или сделать Public (по желанию)
4. Включить Topics (Темы): Настройки группы → Topics → включить

После включения Topics группа автоматически станет супергруппой с форумом. Теперь у неё будет раздел "General" и возможность создавать тематические топики.

Шаг 3: Добавление бота в группу

1. В группе нажать Add Member / Добавить участника
2. Найти бота по username (например @LLuda_bot)
3. Добавить в группу

Шаг 4: Назначение бота администратором

Без прав администратора бот не сможет создавать топики.

1. Настройки группы → Administrators → Add Admin
2. Выбрать бота из списка участников
3. Обязательно включить:
   • ✅ Send Messages (Отправка сообщений)
   • ✅ Manage Topics (Управление темами) — БЕЗ ЭТОГО БОТА НЕ СМОЖЕТ СОЗДАВАТЬ ТОПИКИ
   • Остальные права — по желанию
4. Сохранить

Шаг 5: Получение Chat ID группы

Способ 1 — через API (универсальный):

1. Написать любое сообщение в группу
2. Открыть в браузере:

   https://api.telegram.org/bot<BOT_TOKEN>/getUpdates

   (заменить <BOT_TOKEN> на токен из шага 1)
3. В ответе найти "chat":{"id":-100...} — это и есть Chat ID (отрицательное число вида -1001234567890)

Способ 2 — через URL (для public групп):

1. Открыть группу в Telegram Web
2. URL будет вида https://web.telegram.org/a/#-1001234567890 или для legacy https://t.me/c/1234567890/1
3. Chat ID = -100 + число из URL → -1001234567890

Шаг 6: Получение вашего User ID

1. Написать боту @userinfobot в личные сообщения
2. Он ответит вашим User ID — число вида 198019340

Этот ID нужен для ADMIN_USER_ID. Бот будет принимать сообщения только от этого пользователя и игнорировать всех остальных.

Шаг 7: Настройка .env

cd ~/tg-cc-sync-bot-mcp/main
cp .env.example .env

Открыть .env и заполнить:

BOT_TOKEN=1234567890:AAH...
CHAT_ID=-1001234567890
ADMIN_USER_ID=198019340
PORT=8000

Шаг 8: Запуск

cd ~/tg-cc-sync-bot-mcp/main
docker compose up -d --build

Проверить, что сервер запустился:

curl http://localhost:17005/api/health
# Ожидаемый ответ: {"status":"ok","timestamp":"..."}

curl http://localhost:17005/api/bot-info
# Ожидаемый ответ: имя и username бота

Шаг 9: Регистрация MCP-сервера в Claude Code

claude mcp add-json tg-cc-sync-bot '{"type":"http","url":"http://localhost:17005/mcp"}'

Если используется claude-setup-alexmak — достаточно выполнить /setup-apply, MCP-сервер будет добавлен автоматически.

Шаг 10: Проверка

Запустить новую сессию Claude Code в любом проекте. Если всё настроено правильно:

1. Хук автоматически создаст топик с названием проекта в супергруппе
2. Отправит приветственное сообщение "Сессия началась"
3. Файл .telegram-chat появится в директории проекта

Устранение проблем

Бот не создаёт топики:

• Проверьте, что у бота включено право Manage Topics в настройках администратора
• Проверьте, что Topics включены в настройках группы

Бот не видит сообщения из группы:

• Убедитесь, что Group Privacy отключена: /mybots → Bot Settings → Group Privacy → Turn off
• Убедитесь, что ADMIN_USER_ID совпадает с вашим реальным Telegram ID

Контейнер не запускается:

docker compose logs --tail=50

Health check не проходит:

curl -v http://localhost:17005/api/health

Architecture

Single Node.js process: three components run concurrently via Promise.all.

┌─────────────────────────────────────────────────────┐
│                  Node.js Process                    │
│                                                     │
│  grammY (long polling)  →  MessageBuffer (in-memory)│
│                                  ↓                  │
│  MCP Server (HTTP :17005/mcp) ←──┘                  │
│  REST API   (HTTP :17005/api) ←──┘                  │
└─────────────────────────────────────────────────────┘
         ↕ long polling
    Telegram Bot API
         ↕ forum topics
    Supergroup Chat

• grammY — receives messages from Telegram via long polling, filters by ADMIN_USER_ID, stores in buffer
• MessageBuffer — in-memory Map<topicId, Message[]>, indexed by message ID for deduplication
• MCP Server — Streamable HTTP at /mcp, exposes 5 tools to Claude Code
• REST API — Express at /api/*, for shell scripts and hooks

MCP Tools

REST API

Claude Code Integration

1. Register MCP server

claude mcp add-json tg-cc-sync-bot '{"type":"http","url":"http://localhost:17005/mcp"}'

2. Create per-project topic config

In your project root, create .telegram-chat:

{"topic_id": 123}

Add to .gitignore:

.telegram-chat

Each project gets its own forum topic — all notifications are organized in one supergroup.

3. PostToolUse hook (automatic polling)

Add telegram-check.sh as a PostToolUse hook in ~/.claude/settings.json. The hook reads .telegram-chat from the current project and polls /api/poll after each tool call. If new messages are present, Claude Code sees them.

See $CLAUDE_SETUP_REPO/hooks/ for the hook implementation.

Usage in Claude Code sessions

Send a status update to Telegram:
→ send_message(topic_id=123, text="Starting deployment...", parse_mode="HTML")

Check for human replies:
→ poll_messages(topic_id=123, since_id=0)

Create a topic for a new project:
→ create_topic(title="my-project")

Kill Switch

Set NOTELEGRAM=1 to disable all Telegram hooks without changing config:

NOTELEGRAM=1 claude

All hook scripts check this variable and exit immediately. The MCP server itself is unaffected — only hooks are skipped.

Environment Variables

Development

All tests run offline. Bot and HTTP connections are mocked — no real Telegram API calls in tests.

License

MIT