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キー（シークレット）（画像で見た「Advanced settings」内の2つのフィールド）

• サーバーをインターネットに公開するための無料ホスティングアカウント（例：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から次のようなURLが提供されます：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)