Kintone OAuth MCP Server

Un servidor MCP de ejemplo para kintone que utiliza OAuth, desplegable en Cloudflare Workers.

Documentación

Servidor remoto de Model Context Protocol (MCP) para kintone vía OAuth en Cloudflare Workers

Este es un código de ejemplo de un servidor de Model Context Protocol (MCP) para kintone que se puede implementar como Cloudflare Workers.

No es necesario configurar el programa localmente; se puede usar desde Claude o ChatGPT en versión web.

Mediante la autenticación OAuth, se logra una integración segura con kintone sin almacenar información confidencial como claves de API localmente. Una vez implementado, todos los usuarios que utilicen el mismo dominio cybozu.com pueden compartirlo y usarlo.

🚀 Plataformas con compatibilidad verificada

Al 11 de septiembre de 2025, en ChatGPT Web parece estar disponible como versión beta habilitando Configuración → Conectores → Configuración avanzada → Modo desarrollador con una cuenta Pro o Plus de ChatGPT.

📋 Entorno requerido

Cuenta de Cloudflare
Privilegios de administrador en el dominio cybozu.com (para crear el cliente OAuth)
Node.js 18 o superior
CLI de Wrangler

🔧 Pasos de configuración

1. Crear un cliente OAuth en la administración común de cybozu.com

Agregue un cliente OAuth siguiendo la documentación oficial de Cybozu.

Elementos de configuración:

Nombre del cliente: Un nombre fácil de identificar (ejemplo: «kintone MCP Server»)
Endpoint de redirección: Configure temporalmente https://localhost:8788/callback
Alcances: Seleccione lo siguiente
- k:app_record:read - Lectura de registros
- k:app_record:write - Escritura de registros
- k:app_settings:read - Lectura de configuración de la aplicación
- k:app_settings:write - Escritura de configuración de la aplicación
- k:file:read - Lectura de archivos
- k:file:write - Escritura de archivos

Anote el «ID de cliente» y el «Secreto de cliente» que se muestran después de guardar.
En «Configuración de usuarios» del cliente OAuth, especifique los usuarios que podrán usar este servidor MCP.

2. Configuración del proyecto

# リポジトリのクローン
git clone https://github.com/r3-yamauchi/kintone-oauth-mcp-server-cfw.git
cd kintone-oauth-mcp-server-cfw

# 依存関係のインストール
npm install

3. Configuración de variables de entorno

Escriba los valores anotados al crear el cliente OAuth en el archivo de configuración de Wrangler ( wrangler.jsonc ):

"vars": {
   "CYBOZU_CLIENT_ID": "<your cybozu.com client id>",
   "CYBOZU_CLIENT_SECRET": "<your cybozu.com client secret>",
   "CYBOZU_SUBDOMAIN": "<your cybozu.com sub domain>", # your cybozu.com subdomain
   "COOKIE_ENCRYPTION_KEY": "<your cookie encryption key>", # add any random string here e.g. openssl rand -hex 32
   "WORKER_URL": "<your worker url>"
},

4. Creación del espacio de nombres KV

Ejecute lo siguiente con la CLI de wrangler para crear el espacio de nombres KV:

wrangler kv:namespace create "OAUTH_KV"

Escriba el ID de KV creado en el campo <your cloudflare kv id> dentro del archivo de configuración de Wrangler (wrangler.jsonc).
Ejecute el siguiente comando para implementar en Cloudflare Workers.

wrangler deploy

Una vez completada la implementación, establezca la URL de Workers en el campo «Endpoint de redirección» del cliente OAuth en la pantalla de administración común de cybozu.com, agregando /callback al final. Deberá ingresar https://<your-subdomain>.workers.dev/callback.

Acceso al servidor MCP remoto desde la aplicación web de Claude

Acceda a la pantalla de gestión de integraciones de la aplicación web de Claude y haga clic en «Agregar integración».
El «Nombre de la integración» será el nombre utilizado para identificar el servidor MCP, así que ponga uno fácil de reconocer.
Ingrese https://<your-subdomain>.workers.dev/sse en «URL de integración».

Después de hacer clic en el botón «Agregar», haga clic en «Integrar/Conectar». Aparecerá la pantalla de confirmación de OAuth, así que haga clic en «Aprobar»/«Permitir».

Ahora podrá usar el servidor MCP remoto desde la aplicación web de Claude.

Acceso al servidor MCP remoto desde Claude Desktop

En Claude Desktop, abra Configuración → Desarrollador → Editar configuración y agregue la siguiente configuración. Al reiniciar Claude Desktop, aparecerá la pantalla de inicio de sesión de OAuth; al completar el flujo de autenticación, Claude podrá acceder al servidor MCP.

{
  "mcpServers": {
    "kintone": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-subdomain>.workers.dev/sse"
      ]
    }
  }
}

Explicación

🎯 ¿Qué hace esto?

Es un servidor que permite a los asistentes de IA (como Claude) acceder de forma segura a la API de kintone.

Funciona en Cloudflare Workers y logra la integración con kintone mediante autenticación OAuth sin almacenar credenciales localmente.

🔧 Funciones principales

1. Herramientas disponibles (28 herramientas en total)

Operaciones con registros

getRecords - Obtener lista de registros
getRecord - Obtener un solo registro
addRecord - Agregar un registro
addRecords - Agregar múltiples registros de una vez
updateRecord - Actualizar un registro
getRecordComments - Obtener comentarios de un registro
addRecordComment - Publicar un comentario en un registro
evaluateRecordsAcl - Evaluar permisos de acceso de registros

Configuración de la aplicación

getApp - Obtener información básica de la aplicación
getAppFields - Obtener lista de campos
searchApps - Buscar aplicaciones
getAppSettings - Obtener configuración general de la aplicación
getFormLayout - Obtener diseño del formulario
getViews - Obtener configuración de vistas
getProcessManagement - Obtener configuración de gestión de procesos
getAppReports - Obtener configuración de gráficos
getAppCustomize - Obtener configuración de personalización JavaScript/CSS
getAppActions - Obtener configuración de acciones

Operaciones con archivos

uploadFile - Subir archivo
downloadFile - Descargar archivo

Permisos de acceso

getAppAcl - Obtener permisos de acceso de la aplicación
getRecordAcl - Obtener configuración de permisos de acceso de registros
getFieldAcl - Obtener permisos de acceso de campos

Configuración de notificaciones

getAppNotificationsGeneral - Obtener notificaciones condicionales de la aplicación
getAppNotificationsPerRecord - Obtener notificaciones condicionales de registros
getAppNotificationsReminder - Obtener notificaciones de recordatorio

Gestión de implementación

updateAppCustomize - Actualizar personalización JavaScript/CSS
deployApp - Aplicar la configuración de la aplicación al entorno de producción

2. Doble autenticación OAuth

Autenticación con el cliente MCP (Claude)
Autenticación con la cuenta de kintone/Cybozu

3. Flujo de autenticación

El cliente MCP se conecta
El usuario aprueba en la pantalla de autorización
Redirección a la pantalla de OAuth de kintone
Tras completar la autenticación en kintone, se obtiene el token de acceso
Se establece una conexión segura

🏗️ Arquitectura

Cloudflare Workers - Sin servidor y escalable
KV Storage - Persistencia del estado de OAuth
Cookie cifrada - Memoria de clientes autorizados

💡 Ventajas

Seguro - No es necesario compartir claves de API
Compatible con múltiples usuarios - Varios usuarios pueden usarlo con una sola implementación
Compatible con navegador/escritorio - Se puede usar desde Claude Web o Claude Desktop
Rentable - Sin servidor, se ejecuta solo cuando es necesario

Este proyecto es una implementación completa de un servidor MCP personalizado específicamente para kintone, basado en la plantilla OAuth de GitHub.

Origen de este proyecto

Este proyecto se creó originalmente utilizando la plantilla OAuth de GitHub de Cloudflare:

npm create cloudflare@latest -- kintone-oauth-mcp-server-cfw --template=cloudflare/ai/demos/remote-mcp-github-oauth

Esta plantilla (explicada en la guía de servidores MCP remotos de Cloudflare) proporciona la base para construir servidores MCP con autenticación OAuth. En este proyecto, se modificó esta plantilla para OAuth de Cybozu/kintone, logrando un flujo de autenticación compatible con la implementación de OAuth 2.0 de Cybozu.

Principales cambios respecto a la plantilla original

Para adaptar la plantilla OAuth de GitHub a kintone, se realizaron los siguientes cambios:

Manejador OAuth: Se creó src/cybozu-handler.ts para procesar el flujo OAuth de kintone (reemplazando github-handler.ts)
Endpoints OAuth: Se cambiaron a los endpoints de OAuth de Cybozu:
- Autorización: https://{subdomain}.cybozu.com/oauth2/authorization
- Token: https://{subdomain}.cybozu.com/oauth2/token
Método de autenticación: Ajustado a la especificación OAuth 2.0 de kintone (las credenciales se incluyen en el cuerpo de la solicitud)
Variables de entorno: Cambiadas de GitHub a kintone:
- GITHUB_CLIENT_ID → CYBOZU_CLIENT_ID
- GITHUB_CLIENT_SECRET → CYBOZU_CLIENT_SECRET
- Se agregó CYBOZU_SUBDOMAIN (para el subdominio de kintone)
Alcances: Se utilizan los alcances de la API de kintone
- k:app_record:read - Permiso de lectura de registros
- k:app_record:write - Permiso de escritura de registros
- k:app_settings:read - Permiso de lectura de configuración de la aplicación
- k:app_settings:write - Permiso de escritura de configuración de la aplicación (para actualizar personalizaciones)
- k:file:read - Permiso de lectura de archivos
- k:file:write - Permiso de escritura de archivos

Desarrollo y pruebas locales

Inicie el servidor con HTTPS habilitado:

wrangler dev --local-protocol https

Conéctese a https://localhost:8788/sse con Inspector para probar.

Nota: En el primer acceso, deberá aceptar la advertencia del certificado autofirmado en el navegador.

Solución de problemas de configuración de OAuth

Si se produce un error 401

Verifique los siguientes puntos:

Configuración en Cybozu Developer Network
- Confirme que la URI de redirección coincida exactamente
  - Entorno de producción: https://<your-subdomain>.workers.dev/callback
  - Entorno de desarrollo: https://localhost:8788/callback
- La aplicación OAuth esté «habilitada»
- client_id y client_secret estén copiados correctamente
- Los alcances necesarios estén configurados: k:app_record:read k:app_record:write k:app_settings:read k:app_settings:write k:file:read k:file:write

Verificación de variables de entorno

# .dev.varsファイルまたはwrangler secretsで以下を確認
CYBOZU_CLIENT_ID=<your-client-id>
CYBOZU_CLIENT_SECRET=<your-client-secret>
CYBOZU_SUBDOMAIN=<your-subdomain>
COOKIE_ENCRYPTION_KEY=<random-32-char-string>

Verificación de registros En la consola al iniciar el servidor de desarrollo, verifique:
- OAuth Callback Received - Si la devolución de llamada se recibe correctamente
- Starting Token Exchange - Si se inicia el intercambio de tokens
- El contenido detallado de las respuestas de error
Especificación OAuth de kintone
- Endpoint de autorización: https://{subdomain}.cybozu.com/oauth2/authorization
- Endpoint de token: https://{subdomain}.cybozu.com/oauth2/token
- Método de autenticación: incluir client_id y client_secret en el cuerpo de la solicitud
- Formato de respuesta: JSON
Modo de depuración Para ver registros detallados, puede iniciar el servidor de desarrollo y ejecutar:
```
npm run dev
```

Resumen del funcionamiento

Proveedor OAuth

La biblioteca del Proveedor OAuth es una implementación de servidor OAuth 2.1 para Cloudflare Workers. Esta biblioteca se encarga de todo el flujo OAuth (emisión, verificación y gestión de tokens). Específicamente:

Autenticación del cliente MCP
Gestión de la conexión con el servicio OAuth de kintone
Almacenamiento seguro de tokens y estado de autenticación en el almacenamiento KV

MCP Remote

La biblioteca MCP Remote permite que el servidor proporcione herramientas al cliente:

Define el protocolo de comunicación entre cliente y servidor
Proporciona el método para definir herramientas
Gestiona la serialización/deserialización de solicitudes/respuestas
Mantiene la conexión Server-Sent Events (SSE) entre cliente y servidor

Riesgos de usar un servidor MCP

Asegúrese de tener en cuenta que existe cierto riesgo al usar servidores MCP creados e implementados por otras personas.

Estado actual de kintone AI Lab y los servidores MCP para kintone

«kintone» es una marca registrada de Cybozu, Inc.

El contenido aquí descrito tiene fines informativos y no se brinda soporte individual. Tenga en cuenta que no podemos responder a preguntas sobre la configuración ni a consultas sobre problemas en su propio entorno.