Сервер-мост BILLZ MCP

Этот проект служит «мостом» между BILLZ 2.0 REST API (https://api-admin.billz.ai) и Claude. Claude может читать продукты, продажи, клиентов и другие данные из BILLZ через этот сервер.

1. Что потребуется

• Node.js 18+ (для запуска проекта)

• Client ID (логин) и API ключ (секрет), полученные из BILLZ 2.0 (два поля в «Advanced settings», как показано на изображении)

• Бесплатный хостинг для публикации сервера в интернете (например, Render.com или Railway.app)

Related MCP server: BizDesk MCP

2. О путях эндпоинтов

✅ Часть аутентификации (логин) подтверждена и работает корректно — написана в соответствии с разделом «Аутентификация» официальной документации BILLZ: POST /v1/auth/login + {"secret_token": "..."}.

⚠️ Пути, используемые для продуктов/продаж/клиентов (/v1/products, /v1/orders, /v1/clients, /v1/categories), пока приблизительны — раздел «Методы» в документации BILLZ ещё не подтверждён. Откройте этот раздел и проверьте точные пути: https://billzuz.notion.site/API-c2f91aa254f94f8eb7c1b26415dcb25b

Поэтому сначала используйте только инструмент billz_request (общий запрос) — он работает с любым правильным путём, так как зависит только от корректной аутентификации. Например, вы можете сказать Claude: «Отправь запрос GET /v1/products через billz_request» — если путь неверный, появится сообщение об ошибке, и я исправлю.

3. Тестирование на вашем компьютере (опционально)

cd billz-mcp-server
npm install
cp .env.example .env
# .env faylini ochib, BILLZ_LOGIN, BILLZ_SECRET va MCP_BRIDGE_SECRET
# qiymatlarini to'ldiring
npm start

Если в браузере открывается http://localhost:3000/health, значит сервер работает.

4. Публикация в интернете (на примере Render.com)

1. Загрузите этот проект на GitHub (создайте новый репозиторий, отправьте файлы push).

2. Зарегистрируйтесь на сайте https://render.com.

3. New + → Web Service → выберите ваш репозиторий на GitHub.

4. Настройки:

   • Build Command: npm install

   • Start Command: npm start

5. В разделе Environment добавьте следующее:

   • BILLZ_BASE_URL = https://api-admin.billz.ai

   • BILLZ_LOGIN = (ваш Client ID, например 200400493)

   • BILLZ_SECRET = (ваш API ключ)

   • MCP_BRIDGE_SECRET = (придуманная вами длинная случайная строка)

6. Нажмите кнопку Create Web Service и дождитесь завершения развёртывания.

7. Render предоставит вам адрес, похожий на: https://billz-mcp-server-xxxx.onrender.com

5. Подключение к Claude

1. В Claude откройте окно Customize → Connectors → "+" → Add custom connector (или через Organization Settings владельца организации).

2. Name: BILLZ

3. Remote MCP server URL: https://billz-mcp-server-xxxx.onrender.com/mcp (обязательно должно заканчиваться на /mcp — это не ссылка на Notion или дашборд, теперь это адрес вашего собственного сервера)

4. В поля внутри Advanced settings (если запрашивается не OAuth, а обычный токен) введите значение MCP_BRIDGE_SECRET.

5. Нажмите кнопку Add.

После этого, если вы напишете Claude: «Покажи список продуктов в BILLZ» или «Получи последние 30 дней продаж из BILLZ», он автоматически вызовет инструменты billz_get_products или billz_get_orders.

6. Замечания по безопасности

• Никогда не загружайте файл .env на GitHub (в открытый репозиторий) — обязательно добавьте строку .env в файл .gitignore.

• MCP_BRIDGE_SECRET — защищает ваш сервер от посторонних. Никому его не передавайте.

• Если BILLZ_SECRET где-то раскрыт (например, случайно отправлен в чат), немедленно отзовите его в панели BILLZ и создайте новый.

7. Структура файлов

billz-mcp-server/
├── package.json          # bog'liqliklar ro'yxati
├── .env.example           # sozlamalar namunasi
├── README.md               # ushbu qo'llanma
└── src/
    ├── billzClient.js     # BILLZ API bilan gaplashish (autentifikatsiya + so'rov)
    └── server.js          # MCP server (Claude bilan gaplashadigan qism)