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: MCP Officegest

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 창을 엽니다 (또는 조직 소유자가 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)