BILLZ MCP-Brückenserver

Dieses Projekt dient als "Brücke" zwischen der BILLZ 2.0 REST API (https://api-admin.billz.ai) und Claude. Über diesen Server kann Claude Produkte, Verkäufe, Kunden und andere Daten in BILLZ lesen.

1. Was benötigt wird

• Node.js 18+ (um das Projekt auszuführen)

• Client ID (Login) und API-Schlüssel (Secret) aus BILLZ 2.0 (die beiden Felder in den "Advanced settings", die du im Bild siehst)

• Ein kostenloses Hosting-Konto, um den Server ins Internet zu bringen (z. B. Render.com oder Railway.app)

Related MCP server: BizDesk MCP

2. Über die Endpunkt-Pfade

✅ Der Authentifizierungsteil (Login) ist bestätigt und funktioniert korrekt — er wurde gemäß dem Abschnitt "Аутентификация" in der offiziellen BILLZ-Dokumentation geschrieben: POST /v1/auth/login + {"secret_token": "..."}.

⚠️ Die für Produkte/Verkäufe/Kunden verwendeten Pfade (/v1/products, /v1/orders, /v1/clients, /v1/categories) sind noch vorläufig — denn der Abschnitt "Методы" in der BILLZ-Dokumentation ist noch nicht bestätigt. Öffne diesen Abschnitt und überprüfe die genauen Pfade: https://billzuz.notion.site/API-c2f91aa254f94f8eb7c1b26415dcb25b

Verwende daher zunächst nur das Tool billz_request (allgemeine Anfrage) — es funktioniert mit jedem korrekten Pfad, da es nur von der korrekten Authentifizierung abhängt. Du kannst Claude zum Beispiel sagen: "Sende über billz_request eine GET-Anfrage an den Pfad /v1/products" — wenn der Pfad falsch ist, erscheint eine Fehlermeldung und ich korrigiere ihn.

3. Lokal auf deinem Computer testen (optional)

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

Wenn im Browser http://localhost:3000/health geöffnet wird, heißt das, dass der Server läuft.

4. Ins Internet bringen (am Beispiel Render.com)

1. Lade dieses Projekt auf GitHub hoch (erstelle ein neues Repository und pushe die Dateien).

2. Registriere dich auf der Website https://render.com.

3. New + → Web Service → wähle dein GitHub-Repository.

4. Einstellungen:

   • Build Command: npm install

   • Start Command: npm start

5. Füge im Abschnitt Environment Folgendes hinzu:

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

   • BILLZ_LOGIN = (deine Client ID, z. B. 200400493)

   • BILLZ_SECRET = (dein API-Schlüssel)

   • MCP_BRIDGE_SECRET = (ein langer, zufälliger Text, den du dir selbst ausgedacht hast)

6. Klicke auf die Schaltfläche Create Web Service und warte, bis der Deploy abgeschlossen ist.

7. Render gibt dir eine Adresse wie diese: https://billz-mcp-server-xxxx.onrender.com

5. Mit Claude verbinden

1. Öffne in Claude das Fenster Customize → Connectors → "+" → Add custom connector (oder als Organization Owner über die Organization Settings).

2. Name: BILLZ

3. Remote MCP server URL: https://billz-mcp-server-xxxx.onrender.com/mcp (muss natürlich mit /mcp enden — das ist kein Notion- oder Dashboard-Link, sondern jetzt die Adresse deines eigenen Servers)

4. Gib in die Felder unter Advanced settings (falls nicht OAuth, sondern ein einfacher Token verlangt wird) den Wert von MCP_BRIDGE_SECRET ein.

5. Klicke auf die Schaltfläche Add.

Wenn du danach Claude schreibst: "Zeig mir die Liste der Produkte in BILLZ" oder "Hole die Verkäufe der letzten 30 Tage aus BILLZ", ruft er automatisch die Tools billz_get_products oder billz_get_orders auf.

6. Sicherheitshinweise

• Lade die Datei .env niemals auf GitHub (in ein öffentliches Repository) hoch — füge auf jeden Fall die Zeile .env in die Datei .gitignore ein.

• MCP_BRIDGE_SECRET — das schützt deinen Server vor Fremden. Gib es ebenfalls niemals an jemanden weiter.

• Falls BILLZ_SECRET irgendwo bekannt wird (z. B. wenn es in einen Chat geschrieben wurde), widerrufe es sofort im BILLZ-Panel und erstelle ein neues.

7. Dateistruktur

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)