BILLZ MCP 桥接服务器

该项目充当 BILLZ 2.0 REST API (https://api-admin.billz.ai) 与 Claude 之间的“桥接”。通过此服务器，Claude 可以读取 BILLZ 中的产品、销售、客户及其他数据。

1. 所需条件

• Node.js 18+（用于运行项目）

• 从 BILLZ 2.0 获取的 Client ID（登录名） 和 API 密钥（secret）（图片中“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 说：“通过 billz_request 向 GET /v1/products 路径发送请求”——如果路径错误，将显示错误消息，我会进行修正。

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（创建新仓库，推送文件）。

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 窗口（或由组织 Owner 通过 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 中的产品列表” 或 “从 BILLZ 获取最近 30 天的销售数据”，它将自动调用 billz_get_products 或 billz_get_orders 工具。

6. 安全注意事项

• 切勿将 .env 文件上传到 GitHub（公开仓库）——务必在 .gitignore 文件中添加 .env 行。

• 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)