BILLZ MCP servidor puente

Este proyecto actúa como un "puente" entre la API REST de BILLZ 2.0 (https://api-admin.billz.ai) y Claude. A través de este servidor, Claude puede leer productos, ventas, clientes y otros datos de BILLZ.

1. Requisitos previos

• Node.js 18+ (para ejecutar el proyecto)

• Client ID (login) y API key (secret) obtenidos de BILLZ 2.0 (los dos campos que se ven en "Advanced settings" en la imagen)

• Una cuenta de hosting gratuita para exponer el servidor a internet (por ejemplo Render.com o Railway.app)

Related MCP server: MCP Officegest

2. Acerca de las rutas de endpoints

✅ La parte de autenticación (login) está confirmada y funciona correctamente — está escrita según la sección "Аутентификация" de la documentación oficial de BILLZ: POST /v1/auth/login + {"secret_token": "..."}.

⚠️ Las rutas utilizadas para productos/ventas/clientes (/v1/products, /v1/orders, /v1/clients, /v1/categories) son aún aproximadas — porque la sección "Методы" de la documentación de BILLZ aún no está confirmada. Abra esta sección y verifique las rutas exactas: https://billzuz.notion.site/API-c2f91aa254f94f8eb7c1b26415dcb25b

Por lo tanto, al principio use solo la herramienta billz_request (solicitud general) — funciona con cualquier ruta correcta, ya que solo depende de la autenticación correcta. Por ejemplo, puede decirle a Claude: "Envía una solicitud GET a la ruta /v1/products usando billz_request" — si la ruta es incorrecta, aparecerá un mensaje de error y lo corregiré.

3. Prueba en tu computadora (opcional)

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

Si abres http://localhost:3000/health en el navegador, significa que el servidor está funcionando.

4. Despliegue a internet (ejemplo con Render.com)

1. Sube este proyecto a GitHub (crea un nuevo repositorio, haz push de los archivos).

2. Regístrate en el sitio https://render.com.

3. New + → Web Service → Selecciona tu repositorio de GitHub.

4. Configuración:

   • Build Command: npm install

   • Start Command: npm start

5. En la sección Environment, agrega lo siguiente:

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

   • BILLZ_LOGIN = (tu Client ID, por ejemplo 200400493)

   • BILLZ_SECRET = (tu API key)

   • MCP_BRIDGE_SECRET = (un texto aleatorio largo que tú mismo inventes)

6. Presiona el botón Create Web Service y espera a que termine el despliegue.

7. Render te dará una dirección similar: https://billz-mcp-server-xxxx.onrender.com

5. Conectar con Claude

1. En Claude, abre la ventana Customize → Connectors → "+" → Add custom connector (o el propietario de la organización a través de Organization Settings).

2. Name: BILLZ

3. Remote MCP server URL: https://billz-mcp-server-xxxx.onrender.com/mcp (debe terminar con /mcp — no es un enlace de Notion o dashboard, ahora es la dirección de tu propio servidor)

4. En los campos dentro de Advanced settings (si no es OAuth, sino que se solicita un token simple), ingresa el valor de MCP_BRIDGE_SECRET.

5. Presiona el botón Add.

Después de eso, si le escribes a Claude: "Muestra la lista de productos en BILLZ" o "Obtén las ventas de los últimos 30 días de BILLZ", automáticamente llamará a las herramientas billz_get_products o billz_get_orders.

6. Notas de seguridad

• Nunca subas el archivo .env a GitHub (a un repositorio público) — asegúrate de agregar la línea .env al archivo .gitignore.

• MCP_BRIDGE_SECRET protege tu servidor de extraños. No se lo des a nadie.

• Si BILLZ_SECRET se expone en algún lugar (por ejemplo, si se escribe en un chat), revócalo de inmediato en el panel de BILLZ y crea uno nuevo.

7. Estructura de archivos

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)