Servidor MCP de Rakuraku Hanbai

Este es un servidor MCP que permite llamar a las siguientes API desde los "conectores personalizados" de Claude, basado en el manual de integración de API de Rakuraku Hanbai (RAKUS) (2025/02, 15.ª edición).

• Carga de archivos / Importación de archivos CSV / Importación de datos CSV / Verificación del estado de importación CSV / Exportación CSV

• Registro / Actualización / Eliminación / Consulta de registros

Preparación previa (en el lado de Rakuraku Hanbai)

1. Es obligatorio contratar la opción de integración de API y configurar la restricción de acceso por IP (capítulos 1 y 5 del manual). Permita la IP de origen del servidor de despliegue en Configuración de administrador > pestaña Configuración de seguridad > Configuración relacionada con la restricción de acceso por IP. (En PaaS sin IP fija, como Render, puede ser necesario utilizar el complemento de IP de salida estática).

2. Emita y confirme el token de API en la pantalla de configuración de usuario (capítulo 3 del manual).

3. Los "dbSchemaId", "importId", "ID de elemento", etc. de cada DB se pueden consultar en Configuración de administrador > pestaña Funciones de mantenimiento > Información de parámetros de API.

Procedimiento de despliegue (Render, versión detallada)

Para quienes usan PaaS por primera vez, hemos recopilado el procedimiento completo, desde el push a GitHub hasta la conexión con Claude, en RENDER_DEPLOY.md. Consulte primero ese documento. Es compatible con el despliegue mediante Blueprint usando render.yaml.

Resumiendo los puntos clave:

1. Haga push de esta carpeta a un repositorio de GitHub.

2. Cree un Web Service desde Blueprint (render.yaml) en Render (plan starter o superior).

3. Configure las variables de entorno RAKURAKU_DOMAIN / RAKURAKU_ACCOUNT / RAKURAKU_API_TOKEN / MCP_SHARED_SECRET.

4. Active "Static Outbound IP Addresses" en la pantalla de Configuración y registre la IP fija mostrada en la restricción de acceso por IP de Rakuraku Hanbai.

5. Registre https://<destino_de_despliegue>.onrender.com/mcp como URL del conector de Claude.

También se puede desplegar en otros entornos (Railway / Fly.io / VPS propio + PM2, etc.) siempre que se ejecute Node.js 18 o superior, con un procedimiento similar.

Configuración del conector en el lado de Claude

1. Abra "Agregar conector personalizado" en la pantalla de configuración de Claude.ai.

2. Complete cada campo.

   • Nombre: opcional (ejemplo: Rakuraku Hanbai)

   • URL del servidor MCP remoto: https://<destino_de_despliegue>/mcp

   • OAuth Client ID / Secret: puede dejarlos en blanco (este servidor usa un método simple de secreto compartido).

3. Si configuró MCP_SHARED_SECRET, configure el conector para que envíe el encabezado Authorization: Bearer <MCP_SHARED_SECRET>. (Es posible que la interfaz actual de conectores personalizados de Claude.ai no permita especificar encabezados adicionales directamente. En ese caso, deje MCP_SHARED_SECRET vacío para operar, o protéjalo con restricciones de acceso por IP o un middleware de autenticación propio).

4. Haga clic en "Agregar" para conectarse.

Verificación de funcionamiento local

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

Desde otra terminal, verifique la conectividad:

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

Lista de herramientas proporcionadas

Notas

• Los ID de elemento (por ejemplo, "105110") que se especifican en values de las API de registro/actualización de registros, etc., varían según la DB. Verifíquelos previamente en la pantalla "Información de parámetros de API" y solicite la operación a Claude después de indicarle "el ID de elemento de esta DB es XX".

• La API de Rakuraku Hanbai tiene un límite de 20 solicitudes por minuto (capítulo 5 del manual). Tenga cuidado al manejar grandes volúmenes de datos.

• No comparta RAKURAKU_API_TOKEN con terceros. Se recomienda utilizar la función de variables de entorno (Secret) del destino de despliegue y no escribirlo directamente en el código o en el repositorio de Git.