Rakuraku Sales MCP Server

This is an MCP server that allows you to call the following APIs from Claude's "Custom Connector" based on the Rakuraku Sales (RAKUS) API Integration Manual (2025/02, 15th edition).

• File upload / CSV file import / CSV data import / CSV import status check / CSV export

• Record create / update / delete / retrieve

Prerequisites (Rakuraku Sales side)

1. API integration option contract + IP access restriction settings are required (Manual, Chapter 1, Section 5). Allow the source IP of the deployment server in Security Settings > IP Access Restrictions. (If you are using a PaaS without a fixed IP, such as Render, you will need to use static outbound IP addresses.)

2. Issue and confirm the API token in the User Settings screen (Manual, Chapter 3).

3. Check the dbSchemaId, importId, and field IDs for each DB in Admin Settings > Maintenance Features > API Parameter Information.

Deployment Procedure (Render / Detailed)

For those new to PaaS, we have compiled a step-by-step guide from pushing to GitHub to connecting with Claude in RENDER_DEPLOY.md. Please start there. Blueprint deployment using render.yaml is supported.

Here are the key points:

1. Push this folder to a GitHub repository

2. Create a Web Service from the Blueprint (render.yaml) on Render (plan: starter or higher)

3. Set RAKURAKU_DOMAIN / RAKURAKU_ACCOUNT / RAKURAKU_API_TOKEN / MCP_SHARED_SECRET in the environment variables

4. Enable "Static Outbound IP Addresses" in the Settings screen, and register the displayed static IPs in Rakuraku Sales' IP access restrictions

5. Register https://<deployment-url>.onrender.com/mcp as the connector URL in Claude

You can also deploy in the same way on other platforms (Railway / Fly.io / your own VPS + PM2, etc.) as long as Node.js 18 or later is available.

Claude Connector Settings

1. Open "Add Custom Connector" in the Claude.ai settings screen.

2. Enter each item.

   • Name: Any name (e.g., Rakuraku Sales)

   • Remote MCP server URL: https://<deployment-url>/mcp

   • OAuth Client ID / Secret: Leave blank (this server uses a simple shared secret method)

3. If MCP_SHARED_SECRET is set, configure the connector to send the header Authorization: Bearer <MCP_SHARED_SECRET>. (Note: The current Claude.ai custom connector UI may not allow you to directly specify additional headers. In that case, leave MCP_SHARED_SECRET empty and protect the server with IP access restrictions or your own authentication middleware.)

4. Click "Add" to connect.

Local Verification

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

Check connectivity from another terminal:

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"}}}'

Provided Tools

Notes

• The field IDs specified in values for the record create/update APIs (e.g., "105110") differ for each DB. Check them in advance on the "API Parameter Information" screen, and tell Claude "The field ID for this DB is XX" before requesting operations.

• The Rakuraku Sales API has a limit of 20 requests per minute (Manual, Chapter 5). Please be careful when processing large amounts of data.

• Do not share RAKURAKU_API_TOKEN with third parties. Use the environment variable (Secret) feature of your deployment platform, and avoid writing it directly in code or Git repositories.