楽楽販売 MCPサーバー

楽楽販売(RAKUS)의 API 연동 매뉴얼(2025/02, 제15판)에 기반하여, 다음 API를 Claude의 '커스텀 커넥터'에서 호출할 수 있게 하는 MCP 서버입니다.

• 파일 업로드 / CSV 파일 임포트 / CSV 데이터 임포트 / CSV 임포트 상황 확인 / CSV 익스포트

• 레코드 등록 / 갱신 / 삭제 / 참조

사전 준비(楽楽販売 측)

1. API 연동 옵션 계약 ＋ IP 액세스 제한 설정이 필수입니다(매뉴얼 1장·5장). 배포 대상 서버의 송신원 IP를, 관리자 설정＞보안 설정 탭＞IP 액세스 제한 관련 설정에서 허가해 주세요. (Render 등 고정 IP를 가지지 않는 PaaS의 경우, 정적 Outbound IP 애드온 이용이 필요할 수 있습니다)

2. 사용자 설정 화면에서 API 토큰을 발행·확정합니다(매뉴얼 3장).

3. 각 DB의 'dbSchemaId' 'importId' '항목 ID' 등은, 관리자 설정＞유지보수 기능 탭＞API 파라미터 정보에서 확인해 주세요.

배포 절차(Render·상세판)

PaaS를 처음 사용하는 분을 위해, GitHub에 push부터 Claude 연결까지 일관된 절차를 RENDER_DEPLOY.md 에 정리해 두었습니다. 먼저 이쪽을 확인해 주세요. render.yaml 을 사용한 Blueprint 배포를 지원합니다.

요점만 쓰면:

1. 이 폴더를 GitHub 리포지토리에 push

2. Render에서 Blueprint(render.yaml)로 Web Service를 생성(플랜은 starter 이상)

3. 환경 변수에 RAKURAKU_DOMAIN / RAKURAKU_ACCOUNT / RAKURAKU_API_TOKEN / MCP_SHARED_SECRET 을 설정

4. Settings 화면에서 'Static Outbound IP Addresses'를 활성화하고, 표시된 고정 IP를 楽楽販売의 IP 액세스 제한에 등록

5. https://<デプロイ先>.onrender.com/mcp 를 Claude의 커넥터 URL로 등록

Render 이외(Railway / Fly.io / 자체 VPS + PM2 등)에서도, Node.js 18 이상이 동작하는 환경이면 동일한 절차로 배포할 수 있습니다.

Claude 측 커넥터 설정

1. Claude.ai의 설정 화면에서 '커스텀 커넥터 추가'를 엽니다.

2. 각 항목을 입력합니다.

   • 이름: 임의(예: 楽楽販売)

   • 원격 MCP 서버 URL: https://<デプロイ先>/mcp

   • OAuth Client ID / Secret: 빈칸으로 OK(이 서버는 간이한 공유 시크릿 방식이기 때문)

3. MCP_SHARED_SECRET 을 설정한 경우, 커넥터가 헤더 Authorization: Bearer <MCP_SHARED_SECRET> 을 송신할 수 있도록 설정해 주세요 (현재 Claude.ai의 커스텀 커넥터 UI에서는 추가 헤더를 직접 지정할 수 없는 경우가 있습니다. 그 경우에는 MCP_SHARED_SECRET 을 비워서 운영하거나, IP 액세스 제한이나 자체 인증 미들웨어로 보호해 주세요).

4. '추가'를 클릭하여 연결합니다.

로컬 동작 확인

npm install
cp .env.example .env
# .env を編集して RAKURAKU_DOMAIN / RAKURAKU_ACCOUNT / RAKURAKU_API_TOKEN を設定
npm start

다른 터미널에서 통신 확인:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

제공 도구 목록

주의 사항

• 레코드 등록/갱신 API 등의 values 에 지정하는 항목 ID(예: "105110")는 DB마다 다릅니다. 사전에 'API 파라미터 정보' 화면에서 확인하고, Claude에 '이 DB의 항목 ID는 〇〇입니다'라고 알린 후 조작을 요청해 주세요.

• 楽楽販売 API에는 1분간 20 리퀘스트 제한이 있습니다(매뉴얼 5장). 대량 데이터를 다룰 때는 주의해 주세요.

• RAKURAKU_API_TOKEN 은 제3자와 공유하지 마세요. 배포 대상의 환경 변수(Secret) 기능을 사용하고, 코드나 Git 리포지토리에 직접 쓰지 않는 것을 권장합니다.