BotVa MCP server
Commit Oct 18, 2026A multi-bot Telegram platform powered by Claude AI that enables team coordination, persistent memory, and dynamic MCP integrations.
Also known as cohe4ko/BotVa
- Stars
- 7
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 18, 2026
- License
- MIT
What is BotVa MCP?
BotVa is a multi-bot Telegram platform powered by Claude AI that enables team coordination, persistent memory, and dynamic MCP integrations.
Summary generated from the project's README
About BotVa MCP server
Managing a coordinated team of specialized AI agents through Telegram is what BotVa enables. This platform allows you to deploy multiple bots from a single Node.js instance, where each bot operates as an isolated process with its own memory, roles, and environment variables. Users can manage these agents via a central web dashboard to configure roles, monitor diagnostics, and handle backups.
Developers can extend bot capabilities by adding MCP servers through environment variables, such as connecting a CRM by adding a Bitrix24 webhook. The system features a sophisticated three-tier memory architecture using SQLite for facts and daily diary logs that undergo nightly consolidation via Claude. For communication, bots can interact with each other using Unix sockets through the Colleague MCP or engage with external users via the TGAP protocol. The platform supports voice interactions using Groq STT and various TTS providers like ElevenLabs or Gemini, alongside image generation and web searching tools.
What you can do with it
- 1Automate long-running background tasksSend a heavy command to a bot and move it to the background so you can continue chatting while it works.
- 2Maintain persistent long-term memoryEnsure your AI agents remember specific facts and user preferences through a structured SQLite-based memory system.
- 3Securely manage API credentialsProvide bots with sensitive keys that are injected into tool calls without ever appearing in the chat history or model context.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecohe4ko/botva is public and reachablegithub.com/cohe4ko/botva ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-18github.com/cohe4ko/botva ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubBotVa
Мульти-бот Telegram-платформа на базі Claude AI. Один сервер -- багато ботів, кожен зі своєю роллю, пам'яттю, знаннями та інтеграціями.
Чим BotVa відрізняється
- Пам'ять як першокласна сутність. Факти в SQLite (topic, tags, access_count) + щоденні diary-логи розмов + щотижневі консолідації через Claude. Консолідація запускається автоматично щоночі
- Команда ботів. Боти спілкуються через Unix-сокети (Colleague MCP), менеджер розподіляє задачі паралельно через
Promise.allSettled() - Повна ізоляція. Кожен бот -- окремий процес, .env, база, знання, пам'ять, голос, роль. Керуються з однієї адмін-панелі
- Живе управління. Веб-панель для створення ботів, галереї зображень, cron-задач, бекапів, діагностики. Модель чату, фонова модель (для сервісних викликів) та reasoning effort змінюються без рестарту, зміни .env потребують рестарту через UI
- Динамічні інтеграції. MCP-сервери підключаються за наявності env-змінних -- додав
BITRIX24_WEBHOOK_URL, перезапустив бота і він отримав CRM. Без зміни коду - Філософія. Базова роль (
_soul.md) -- маніфест: як думати, як спілкуватись, коли мовчати. Не "certainly!", а людська розмова
Ключові можливості
- Кілька ботів з одного інстансу Node.js
- 14 готових ролей -- від персонального асистента до автономного агента
- Пам'ять -- факти з dedup по content-hash, FTS5-пошуком та usefulness-трекінгом, щоденні diary-логи з консолідацією
- Workspace files -- 8-шарова збірка CLAUDE.md (SOUL/TOOLS глобальні, BOT_SOUL/BOT_TOOLS/IDENTITY/ROLE/USER/MEMORY per-bot) з feature-flag блоками
- Голос -- голосові повідомлення та відповіді (Groq STT + Gemini TTS / Edge TTS / ElevenLabs з ротацією ключів)
- Зображення -- генерація та редагування через Gemini з авто-галереєю
- Gemini AI -- друга думка (AskGemini) та пошук з цитатами (GeminiSearch)
- Команда ботів -- спілкування через Unix-сокети, делегування задач, каталог агентів-спеціалістів з keyword matcher
- Планувальник -- cron-задачі та нагадування з режимом
runAgent(виконати як повноцінний запит з інструментами) - Утиліти -- курси валют, час, Python sandbox, email, Telegraph
- Інтеграції -- Google Workspace, розумний дім, будь-які MCP-сервери
- Веб-пошук -- пошук, скрапінг, AI-браузер (Stagehand)
- Адмін-панель -- повний веб-інтерфейс для управління
- Аудіо-рекордер -- фоновий запис з мікрофона (Orange Pi / Mac), VAD-фільтр тиші, транскрипція Whisper
- Бекапи -- повні та per-bot, з SHA256-верифікацією
Швидкий старт
Встановлення на VPS (найшвидший спосіб)
Відкрий https://botva-installer.onrender.com/, введи IP сервера, Telegram-токен -- і через 3-5 хвилин бот працює. Детальніше: DEPLOY.md
Локальне встановлення
# 1. Клонувати
git clone https://github.com/cohe4ko/BotVa.git BotVa
cd BotVa
# 2. Встановити залежності та зібрати
./scripts/deploy.sh setup
# 3. Створити першого бота (варіант A: CLI)
npm run new-bot -- my-bot personal-assistant --emoji 🧑💼 --name "Мій Бот"
# 3. Створити першого бота (варіант B: веб-інтерфейс)
./scripts/deploy.sh admin # Запустити адмін-панель
# Відкрий http://localhost:3000 → Create Bot
# Токен та chat ID вводяться у формі створення
# 4. Налаштувати токени (якщо CLI)
# Відкрий bots/my-bot/.env:
# - TELEGRAM_BOT_TOKEN (отримати у @BotFather в Telegram)
# - ALLOWED_CHAT_ID (надіслати /chatid боту після запуску)
# 5. Залогінитись в Claude CLI
# Запустити адмін-панель → Термінал (/terminal)
# та пройти логін через підписку (не API key)
# 6. Запустити
./scripts/deploy.sh start
Після запуску напиши боту в Telegram -- він відповість.
Обери роль, введи Telegram-токен від @BotFather та chat ID. API-ключі можна додати пізніше.
Після створення — структура файлів та наступні кроки.
Ролі ботів
При створенні бота обираєш роль -- вона визначає спеціалізацію, інструменти та стиль.
| Роль | Slug | Опис |
|---|---|---|
| Персональний асистент | personal-assistant |
Повсякденні задачі, розклад, CRM, розумний дім |
| Дослідник | researcher |
Глибокий аналіз, верифікація фактів, звіти |
| Здоров'я | health-advisor |
Моніторинг показників, аналізи, рекомендації |
| Академічний | academic |
Наукові статті, методологія, PhD, викладання |
| Креативний | creative |
Дизайн, зображення, презентації, копірайтинг |
| Продажі | sales |
Ліди, угоди, аналіз продажів, пропозиції |
| Планувальник | planner |
Задачі, дедлайни, пріоритизація |
| База знань | knowledge-base |
Документація, FAQ, пошук знань |
| Менеджер | manager |
Координація команди ботів, делегування |
| Продукт/Ринок | product-market |
CRM-аналітика, позиціонування, конкуренти |
| Вебмайстер | webmaster |
Сайт, контент, деплой, SEO |
| Дебати та дослідження | debate-researcher |
Аналіз з протилежних позицій |
| Автономний агент | autonomous |
Довготривалі задачі без участі користувача, власний _soul_autonomous.md |
| Dome Engineer | dome-engineer |
Інженерні задачі, діагностика, оркестрація технічних workflow |
npm run new-bot -- <slug> <роль> [--emoji 🤖] [--name "Назва"]
Можливості
Telegram
Перша взаємодія з ботом — привітання, налаштування профілю, нагадування та пошук з уточнюючими питаннями:
Повідомлення, надіслане поки бот працює, не перериває його: модель отримує його на найближчій межі кроку і враховує, не повторюючи зроблене. Довгу команду чи субагента можна відправити у фон кнопкою «⏩ У фон» на повідомленні з прогресом — бот одразу перейде до нового повідомлення, а коли задача завершиться, сам напише результат. Фонова задача живе до BACKGROUND_TASK_MAX_MS (типово 30 хв) після останньої відповіді.
Голос
Бот розуміє голосові повідомлення та може відповідати голосом. STT через Groq Whisper (потрібен GROQ_API_KEY). Інструмент TranscribeAudio дає боту самостійно транскрибувати локальні файли — якщо файл понад 24 MB або в неприйнятному форматі, ffmpeg автоматично перекодовує в 16 kHz mono FLAC і ріже на 25-хвилинні чанки, транскрипти склеюються. Три TTS-провайдери: Gemini TTS (безкоштовно, дефолт — виразні мультимовні голоси через GOOGLE_API_KEY, стиль керується промптом, fallback на Edge при помилці/квоті), Edge-TTS (безкоштовно, без лімітів) та ElevenLabs (вища якість, локальний JSON-стор ключів з ручною ротацією, відстеженням ліміту/помилок, fallback на Gemini/Edge при вичерпанні квоти). Провайдери конфігуруються окремо для автовідповідей (TTS_PROVIDER_REPLY) та tool-синтезу (TTS_PROVIDER_TOOL). Агент сам розмічає емоційний тон озвучки: маркер [[tone: ...]] наприкінці відповіді (вирізається з тексту) або параметр tone інструмента TextToSpeech — Gemini TTS передає емоцію голосом. Sentence-aware чанкування довгих текстів (до 20 фрагментів) з надсиланням послідовних voice-повідомлень. Голоси, швидкість, stability/similarity — через вкладку /audio в адмінці. Команда /voice вмикає/вимикає голосові відповіді, /usage показує статус ключів ElevenLabs.
Зображення
Генерація та редагування через Gemini (GOOGLE_API_KEY). Команда /img опис або просто попроси в чаті. Всі зображення зберігаються в галереї.
Пам'ять
Трирівнева система: факти (постійне сховище з topic та tags), щоденні markdown-логи, workspace-файли (USER.md, MEMORY.md). Консолідація о NIGHT_OWL_HOUR.
Планувальник
Cron-задачі: /schedule 0 9 * * * Що в мене на сьогодні?. Стандартний 5-полевий cron.
Команда ботів
Менеджер координує роботу, боти спілкуються через Colleague MCP (Unix-сокети). Кожен бот може звернутись до менеджера через ask_manager().
Нового бота можна створити без @BotFather: CreateBot без токена надсилає кнопку, що відкриває вікно створення бота в самому Telegram, — після підтвердження бот отримує токен, доступ до нього лишається тільки власнику. Потрібно один раз увімкнути керування ботами для бота-творця в @BotFather Mini App. RotateBotToken замінює токен такого бота, якщо старий витік.
Боти інших людей (TGAP)
Бот може напряму спитати бота іншої людини (AskExternalBot): «спитай у @petro_bot, коли Петро вільний». Бот друга готує чернетку з read-only інструментами, показує її власнику з кнопками «Надіслати / Змінити / Відхилити / Заблокувати», і лише після підтвердження відповідає. Відповідь чесно позначає, чи її підтвердив власник. Невідомі боти, ліміти ходів і rate limit, захист від зациклення — за протоколом TGAP. Замість однієї чернетки власник бачить 2–3 варіанти, що різняться по суті (відповісти повністю, частково, відмовити), і надсилає потрібний кнопкою «✅ 1/2/3»; «🔄 Інакше» — написати своїми словами, що змінити, і отримати нові варіанти; «✏️ Свій текст» — надіслати власний. Пропозиції (TGAP Extended): «домовся з @x_bot про зустріч» іде як proposal, інша сторона погоджується, відмовляє або пропонує інакше; якщо власник назвав межі («будь-який день після 14:00»), бот після підтвердження кнопкою сам погоджується або торгується в їх межах, а все поза ними приносить власнику. Межі тій стороні не показуються, підсумок домовленості приходить власнику. ManageExternalBots — список ботів і рівні довіри. Відповідь на питання повертається в той чат, звідки його поставили, а картки на схвалення вхідних запитів — завжди власнику (перший id в ALLOWED_CHAT_ID).
Вмикається TGAP_ENABLED=1 у .env бота; потрібен Bot-to-Bot Communication Mode у @BotFather для обох ботів. TGAP_OWNER_NAME — ім'я у «візитці» бота (порожнє — анонімно), TGAP_ACCEPT_FROM=known_only — відмовляти невідомим ботам, TGAP_DRAFT_TOOLS — додаткові read-only MCP-інструменти для чернетки (mcp__<server>__<tool>, через кому).
Секрети
Логіни, паролі й ключі API лежать у зашифрованому сховищі бота. Власник додає їх командою /secret add <назва>, а повідомлення зі значенням бот одразу видаляє. Агент бачить лише назви (ListSecrets) і пише {{secret:назва.поле}} у виклику інструмента: значення підставляється перед запуском і вирізається з результату, тому не потрапляє ні в контекст моделі, ні в історію сесії. У повідомлення, листи, пам'ять і запити до інших ботів секрет не підставляється. Боту іншої людини на BotVa секрет можна передати через TGAP: кнопка «🔑 Передати секрет» на картці запиту, /secret share або ShareSecret. Секрет іде зашифрованим під X25519-ключ отримувача, і його власник вирішує, чи прийняти. Передачу можна відкликати в /secret або в адмінці (вкладка «Секрети»); бот на тому боці видаляє секрет сам.
Логін, збережений у Google Chrome на тому ж Mac, можна взяти прямо звідти: в адмінці (вкладка бота «Секрети» → «Імпорт з Google Chrome»: список збережених логінів з пошуком, назва і кнопка «Імпортувати»), командою /secret import <назва> <сайт> або словами агенту («візьми пароль від сайту з хрому»), тоді він викликає ImportBrowserSecret і власник обирає логін кнопкою. Пароль іде з Chrome одразу в сховище і не проходить ні через чат, ні через Telegram, ні через модель. Під час першого імпорту macOS може попросити доступ до запису «Chrome Safe Storage» у Keychain.
Telegram
Режим сесій у /settings: Назва (одна розмова, бот називає її через NameSession) або Топіки — кожен топік особистого чату окрема розмова зі своєю сесією (топіки вмикаються для бота в @BotFather).
SendMedia (фото, документи, альбоми), SendChecklist (список задач/покупок з чекбоксами), ForwardMessage, SetReaction (реакція emoji + зняття реакції), PinMessage, OpenWebApp (Mini App), AskUser (кнопки, poll із зображеннями в опціях).
Утиліти
CurrencyRates (готівкові курси), GetCurrentTime, RunPython (ізольований: без мережі й ключів, пише лише у свій каталог, файли користувача — тільки на читання), SendEmail (SMTP), PublishTelegraph, ShareFile (файл, папка або .zip/.tar.gz -- багатофайлова сторінка розгортається на сервері в окрему теку з index.html).
Workspace Files
Бот читає та оновлює свої файли між сесіями: USER.md (профіль), MEMORY.md (пам'ять) через ReadWorkspaceFile / WriteWorkspaceFile.
Детальний посібник: MANUAL.md
Інтеграції
Будь-який MCP-сервер можна підключити через mcp-servers.json.
Вбудовані (в комплекті):
| Інтеграція | MCP-сервер | Потрібні змінні |
|---|---|---|
| Playwright (headless Chrome) | playwright-remote |
-- |
| Stagehand (AI-браузер) | stagehand |
GOOGLE_API_KEY |
| Google Calendar, Gmail, Drive | google-workspace |
GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET |
| Home Assistant | home-assistant |
HA_URL, HA_TOKEN |
| Telegram Observer (особистий акаунт) | telegram |
TELEGRAM_API_ID, TELEGRAM_API_HASH |
Інші MCP-сервери (CRM, реклама, наукові бази тощо) додаються як запис в mcp-servers.json та увімкнюються в адмінці System → MCP Servers.
Сервер може мати передумову. envVars — потрібні змінні оточення; requiresFile — файли, які мають існувати (шляхи від кореня проєкту). Друге потрібне там, де сервер вмикається не налаштуванням, а дією: telegram віддає інструменти лише після того, як акаунт справді підключили, бо саме тоді з'являється store/telegram.session. Файл переживає обрив зв'язку і рестарт демона, тож інструменти не зникають на час недоступності — вони просто не з'являються, поки нічого не підключено.
Аудіо-рекордер (Listener)
Система фонового запису аудіо з мікрофонів, автоматична транскрипція (Groq Whisper) та аналіз через Claude.
Компоненти:
| Компонент | Опис | Розташування |
|---|---|---|
| Receiver | HTTP-сервер, приймає WAV, транскрибує, аналізує | scripts/orange-pi-listener/receive-transcript.ts |
| Orange Pi Listener | Python-демон для SBC з мікрофоном | scripts/orange-pi-listener/listener.py |
| Mac Listener | Electron tray app для macOS | scripts/mac-listener/ |
Як працює:
- Пристрій записує аудіо чанками (за замовчуванням 5 хв)
- VAD (Voice Activity Detection) фільтрує тишу — чанки з < 15% мовлення пропускаються
- Чанки з голосом відправляються на Receiver (
POST /audio, multipart WAV) - Receiver транскрибує через Groq Whisper та зберігає щоденні конспекти
Mac Listener (tray app):
cd scripts/mac-listener && npm install && npm start
Env: UPLOAD_URL=http://host:3847/audio, DEVICE_ID=mac-1. Два режими: Toggle (ручний старт/стоп) та Continuous (автоматичні чанки). Вимагає ffmpeg.
Receiver:
npx tsx scripts/orange-pi-listener/receive-transcript.ts
Env: GROQ_API_KEY (або GROQ_API_KEYS), LISTENER_PORT=3847, ANTHROPIC_API_KEY (для аналізу).
Пристрої відображаються в адмін-панелі System → Recorder.
BotVa MCP questions
Can bots communicate with each other?
Yes, bots can communicate through Unix sockets using the Colleague MCP, allowing a manager to distribute tasks in parallel.
How does the memory system work?
It uses a three-level system: facts stored in SQLite with topics and tags, daily markdown conversation logs, and workspace files like USER.md and MEMORY.md.
How can I add new integrations like a CRM?
MCP servers are connected dynamically via environment variables; for example, adding a Bitrix24 webhook URL and restarting the bot grants CRM access.
Is there a way to manage bots via a web interface?
Yes, there is a web admin panel for creating bots, managing image galleries, cron jobs, backups, and diagnostics.