kintone

Un servidor MCP para integrarse con la API REST de kintone. Admite operaciones CRUD, gestión de archivos, comentarios y actualizaciones de estado.

GitHubPrueba este MCPPatrocinado

Documentación

Ejemplo de servidor MCP de kintone (Python3)

Esta es una implementación de ejemplo de un servidor MCP (Model Context Protocol) para integrarse con kintone. Este servidor permite que asistentes de IA (como Claude) lean y operen los datos de kintone.

Características principales

🔐 Autenticación segura: Compatible tanto con autenticación por token de API como con autenticación por contraseña
📊 Operaciones CRUD completas: Crear, leer, actualizar y eliminar registros
📄 Paginación automática: Procesa eficientemente grandes volúmenes de registros
🔍 Funciones de consulta avanzadas: Soporte completo de la sintaxis de consulta de kintone
📎 Gestión de archivos: Compatible con carga y descarga de archivos
💬 Función de comentarios: Agregar y obtener comentarios en registros
🔄 Gestión de estados: Actualización de estados en la gestión de procesos
🚀 Procesamiento asíncrono: Respuestas rápidas y uso eficiente de recursos
🛡️ Manejo robusto de errores: Mensajes de error detallados y manejo adecuado de excepciones
🌐 Soporte de internacionalización: Compatibilidad con campos multilingües

Herramientas disponibles

Operaciones con registros

Nombre de la herramienta	Descripción	Uso principal
`get_record`	Obtener un solo registro	Obtener información detallada de un registro específico
`get_records`	Obtener lista de registros (con paginación)	Buscar y obtener registros que coincidan con las condiciones
`get_all_records`	Obtener automáticamente todos los registros	Obtener grandes volúmenes de registros (paginación automática)
`add_record`	Agregar un solo registro	Crear un nuevo registro
`add_records`	Agregar múltiples registros de una vez (máximo 100)	Creación eficiente de registros mediante procesamiento por lotes
`update_record`	Actualizar un solo registro	Actualizar información de un registro existente
`update_records`	Actualizar múltiples registros de una vez (máximo 100)	Actualización eficiente de registros mediante procesamiento por lotes

Operaciones de comentarios y estados

Nombre de la herramienta	Descripción	Uso principal
`get_comments`	Obtener comentarios de un registro	Consultar el historial de comunicación
`add_comment`	Agregar comentario a un registro	Publicar comentarios con menciones
`update_status`	Actualizar estado de un registro	Avanzar en el flujo de trabajo
`update_statuses`	Actualizar estados de múltiples registros	Procesamiento eficiente de flujos de trabajo

Gestión de archivos y aplicaciones

Nombre de la herramienta	Descripción	Uso principal
`upload_file`	Cargar archivo	Registrar archivos adjuntos
`download_file`	Descargar archivo	Obtener archivos adjuntos
`get_app`	Obtener información de la aplicación	Consultar la configuración de la aplicación
`get_apps`	Buscar y obtener lista de aplicaciones	Explorar aplicaciones disponibles
`get_form_fields`	Obtener configuración de campos del formulario	Comprender la estructura de la aplicación

Requisitos

Python 3.12 o superior
uv (recomendado)
Permisos de acceso al entorno kintone
Token de API o credenciales de usuario

Configuración del cliente MCP

Configuración de Claude Desktop

Para usar este servidor con Claude Desktop, agregue lo siguiente al archivo de configuración.

Ubicación del archivo de configuración

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Uso de uvx (recomendado)

Configuración para ejecutar directamente desde GitHub:

{
  "mcpServers": {
    "kintone": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/r3-yamauchi/kintone-mcp-server-python3.git",
        "kintone-mcp-server-python3"
      ],
      "env": {
        "KINTONE_DOMAIN": "your-subdomain.cybozu.com",
        "KINTONE_USERNAME": "your-username",
        "KINTONE_PASSWORD": "your-password"
      }
    }
  }
}

Importante:

Reemplace KINTONE_DOMAIN con el valor real (ejemplo: dev-demo.cybozu.com)
La autenticación utiliza autenticación por contraseña si se especifican tanto el nombre de usuario como la contraseña; de lo contrario, se utiliza autenticación por token de API
Las variables de entorno se escriben directamente dentro de claude_desktop_config.json
Reinicie Claude Desktop después de cambiar la configuración

Configuración de VS Code

Si utiliza la extensión MCP de VS Code:

{
  "mcp.servers": {
    "kintone": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/r3-yamauchi/kintone-mcp-server-python3.git",
        "kintone-mcp-server-python3"
      ],
      "env": {
        "KINTONE_DOMAIN": "your-subdomain.cybozu.com",
        "KINTONE_API_TOKEN": "your-api-token"
      }
    }
  }
}

Ejemplo de configuración para múltiples entornos

Para gestionar por separado los entornos de producción y desarrollo:

{
  "mcpServers": {
    "kintone-prod": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/r3-yamauchi/kintone-mcp-server-python3.git",
        "kintone-mcp-server-python3"
      ],
      "env": {
        "KINTONE_DOMAIN": "your-subdomain.cybozu.com",
        "KINTONE_API_TOKEN": "prod-api-token"
      }
    },
    "kintone-dev": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/r3-yamauchi/kintone-mcp-server-python3.git",
        "kintone-mcp-server-python3"
      ],
      "env": {
        "KINTONE_DOMAIN": "your-subdomain.cybozu.com",
        "KINTONE_USERNAME": "dev-user",
        "KINTONE_PASSWORD": "dev-password"
      }
    }
  }
}

Puntos clave de configuración

Ventajas de uvx
- No requiere instalación previa
- Siempre ejecuta la versión más reciente
- Evita conflictos de dependencias
Notas de seguridad
- Debe guardar información confidencial (nombre de usuario, contraseña, token de API) en texto plano en claude_desktop_config.json para acceder a kintone
- No comparta este archivo con otras personas
- Tenga cuidado de no confirmarlo en repositorios Git

Solución de problemas

Problemas comunes y soluciones

Error de conexión

Error: Failed to connect to kintone

Solución:

Verifique que KINTONE_DOMAIN sea correcto (ejemplo: dev-demo.cybozu.com)
Verifique la conexión de red
Verifique la configuración del firewall

Error de autenticación

Error: Authentication failed (401)

Solución:

Verifique que el nombre de usuario, la contraseña o el token de API sean correctos
Verifique que el token de API tenga los permisos necesarios
Verifique que el token de API esté habilitado en la configuración de la aplicación

Error de permisos

Error: Permission denied (403)

Solución:

Verifique que el usuario tenga permisos de acceso a la aplicación
Verifique que el token de API tenga los permisos necesarios
Verifique los permisos de acceso a los registros

Modo de depuración

Para generar registros detallados:

export LOG_LEVEL=DEBUG
uvx --from git+https://github.com/r3-yamauchi/kintone-mcp-server-python3.git kintone-mcp-server-python3

Instalación local del código fuente

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

# 依存関係をインストール
pip install -e .

# 実行
python -m kintone_mcp_server_python3

Ejemplos de uso

Uso básico

get_records

Obtiene registros de la aplicación kintone con función de paginación.

Parámetros:

app (obligatorio): ID de la aplicación
query (opcional): Cadena de consulta para filtrar registros
fields (opcional): Lista de códigos de campo a obtener
limit (opcional): Número máximo de registros a obtener (predeterminado: 100, máximo: 500)
offset (opcional): Desplazamiento para paginación (predeterminado: 0)

Ejemplo de uso:

{
  "tool": "get_records",
  "arguments": {
    "app": 123,
    "query": "Status = \"Open\"",
    "fields": ["Title", "Status", "Created_datetime"],
    "limit": 100
  }
}

get_all_records

Obtiene todos los registros de la aplicación kintone (procesa la paginación automáticamente).

Parámetros:

app (obligatorio): ID de la aplicación
query (opcional): Cadena de consulta para filtrar registros
fields (opcional): Lista de códigos de campo a obtener

Ejemplo de uso:

{
  "tool": "get_all_records",
  "arguments": {
    "app": 123,
    "query": "Created_datetime > \"2024-01-01\"",
    "fields": ["Title", "Status"]
  }
}

get_apps

Busca y obtiene información de las aplicaciones kintone.

Parámetros:

name (opcional): Búsqueda por coincidencia parcial del nombre de la aplicación (sin distinguir mayúsculas y minúsculas)
ids (opcional): Lista de IDs de aplicación a obtener
codes (opcional): Lista de códigos de aplicación a obtener (coincidencia exacta, distingue mayúsculas y minúsculas)
space_ids (opcional): Filtrar por ID de espacio
limit (opcional): Número máximo de aplicaciones a obtener (predeterminado: 100, máximo: 100)
offset (opcional): Desplazamiento para paginación (predeterminado: 0)

Ejemplo de uso:

{
  "tool": "get_apps",
  "arguments": {
    "name": "顧客",
    "limit": 50
  }
}

Ejemplo de respuesta:

{
  "apps": [
    {
      "appId": "123",
      "code": "CUSTOMER_APP",
      "name": "顧客管理",
      "description": "顧客情報を管理するアプリです",
      "spaceId": "10",
      "createdAt": "2024-01-01T00:00:00Z",
      "creator": {
        "code": "user1",
        "name": "山田太郎"
      },
      "modifiedAt": "2024-01-15T10:30:00Z",
      "modifier": {
        "code": "user2",
        "name": "佐藤花子"
      }
    }
  ],
  "count": 1
}

get_record

Obtiene un solo registro.

Parámetros:

app (obligatorio): ID de la aplicación
id (obligatorio): ID del registro

Ejemplo de uso:

{
  "tool": "get_record",
  "arguments": {
    "app": 123,
    "id": 456
  }
}

add_record

Agrega un solo registro a la aplicación kintone.

Parámetros:

app (obligatorio): ID de la aplicación
record (obligatorio): Objeto con códigos de campo y valores

Ejemplo de uso:

{
  "tool": "add_record",
  "arguments": {
    "app": 123,
    "record": {
      "Title": {"value": "新しいタスク"},
      "Status": {"value": "未着手"},
      "Assignee": {"value": [{"code": "user1"}]}
    }
  }
}

add_records

Agrega múltiples registros de una vez (máximo 100).

Parámetros:

app (obligatorio): ID de la aplicación
records (obligatorio): Matriz de datos de registros

Ejemplo de uso:

{
  "tool": "add_records",
  "arguments": {
    "app": 123,
    "records": [
      {
        "Title": {"value": "タスク1"},
        "Status": {"value": "未着手"}
      },
      {
        "Title": {"value": "タスク2"},
        "Status": {"value": "進行中"}
      }
    ]
  }
}

update_record

Actualiza un solo registro.

Parámetros:

app (obligatorio): ID de la aplicación
id (opcional): ID del registro (se requiere id o update_key)
update_key (opcional): Campo y valor que sirven como clave de actualización
record (obligatorio): Campos y valores a actualizar
revision (opcional): Número de revisión (para bloqueo optimista)

Ejemplo de uso:

{
  "tool": "update_record",
  "arguments": {
    "app": 123,
    "id": 456,
    "record": {
      "Status": {"value": "完了"},
      "CompletedDate": {"value": "2024-12-07"}
    }
  }
}

update_records

Actualiza múltiples registros de una vez (máximo 100).

Parámetros:

app (obligatorio): ID de la aplicación
records (obligatorio): Matriz de datos de actualización

Ejemplo de uso:

{
  "tool": "update_records",
  "arguments": {
    "app": 123,
    "records": [
      {
        "id": 456,
        "record": {"Status": {"value": "完了"}}
      },
      {
        "id": 789,
        "record": {"Status": {"value": "保留"}}
      }
    ]
  }
}

get_comments

Obtiene los comentarios de un registro.

Parámetros:

app (obligatorio): ID de la aplicación
record (obligatorio): ID del registro
order (opcional): Orden de clasificación ("asc" o "desc", predeterminado: "desc")
offset (opcional): Desplazamiento (predeterminado: 0)
limit (opcional): Número de elementos a obtener (máximo 10, predeterminado: 10)

Ejemplo de uso:

{
  "tool": "get_comments",
  "arguments": {
    "app": 123,
    "record": 456,
    "order": "desc",
    "limit": 5
  }
}

add_comment

Agrega un comentario a un registro.

Parámetros:

app (obligatorio): ID de la aplicación
record (obligatorio): ID del registro
text (obligatorio): Texto del comentario
mentions (opcional): Matriz de información de menciones

Ejemplo de uso:

{
  "tool": "add_comment",
  "arguments": {
    "app": 123,
    "record": 456,
    "text": "作業が完了しました。",
    "mentions": [
      {"code": "user1", "type": "USER"}
    ]
  }
}

update_status

Actualiza el estado de un registro.

Parámetros:

app (obligatorio): ID de la aplicación
id (obligatorio): ID del registro
action (obligatorio): Nombre de la acción
assignee (opcional): Nombre de inicio de sesión del responsable
revision (opcional): Número de revisión

Ejemplo de uso:

{
  "tool": "update_status",
  "arguments": {
    "app": 123,
    "id": 456,
    "action": "承認する",
    "assignee": "user2"
  }
}

update_statuses

Actualiza los estados de múltiples registros de una vez (máximo 100).

Parámetros:

app (obligatorio): ID de la aplicación
records (obligatorio): Matriz de datos de actualización de estados

Ejemplo de uso:

{
  "tool": "update_statuses",
  "arguments": {
    "app": 123,
    "records": [
      {
        "id": 456,
        "action": "承認する"
      },
      {
        "id": 789,
        "action": "却下する"
      }
    ]
  }
}

upload_file

Carga un archivo a kintone.

Parámetros:

file_path (obligatorio): Ruta del archivo a cargar

Ejemplo de uso:

{
  "tool": "upload_file",
  "arguments": {
    "file_path": "/path/to/document.pdf"
  }
}

Ejemplo de respuesta:

{
  "fileKey": "20241207103000-1234567890ABCDEF"
}

download_file

Descarga un archivo de kintone.

Parámetros:

file_key (obligatorio): Clave del archivo
save_path (obligatorio): Ruta del archivo de destino

Ejemplo de uso:

{
  "tool": "download_file",
  "arguments": {
    "file_key": "20241207103000-1234567890ABCDEF",
    "save_path": "/path/to/save/document.pdf"
  }
}

get_app

Obtiene información detallada de la aplicación.

Parámetros:

id (obligatorio): ID de la aplicación

Ejemplo de uso:

{
  "tool": "get_app",
  "arguments": {
    "id": 123
  }
}

get_form_fields

Obtiene la configuración de los campos del formulario de la aplicación.

Parámetros:

app (obligatorio): ID de la aplicación
lang (opcional): Código de idioma (ejemplo: "ja", "en")

Ejemplo de uso:

{
  "tool": "get_form_fields",
  "arguments": {
    "app": 123,
    "lang": "ja"
  }
}

Ejemplo de respuesta:

{
  "properties": {
    "Title": {
      "type": "SINGLE_LINE_TEXT",
      "code": "Title",
      "label": "タイトル",
      "required": true
    },
    "Status": {
      "type": "DROP_DOWN",
      "code": "Status",
      "label": "ステータス",
      "options": {
        "未着手": {"label": "未着手", "index": "0"},
        "進行中": {"label": "進行中", "index": "1"},
        "完了": {"label": "完了", "index": "2"}
      }
    }
  },
  "revision": "5"
}

Desarrollo

Configuración del entorno de desarrollo

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

# 仮想環境の作成（推奨）
python -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate  # Windows

# 開発用依存関係をインストール
pip install -e ".[dev]"

# 環境変数の設定
cp .env.example .env
# .envファイルを編集して必要な設定を追加

# pre-commitフックの設定（推奨）
pre-commit install

Pruebas

# すべてのテストを実行
pytest

# カバレッジレポート付きでテスト実行
pytest --cov=kintone_mcp_server_python3 --cov-report=html

# 特定のテストファイルを実行
pytest tests/test_auth.py

# 特定のテストを実行
pytest tests/test_auth.py::test_api_token_auth -v

Gestión de calidad del código

# コードフォーマット（Black）
black src tests

# リンティング（Ruff）
ruff check src tests
ruff check src tests --fix  # 自動修正

# 型チェック（MyPy）
mypy src

# すべてのチェックを実行
make lint  # Makefileがある場合
# または
black src tests && ruff check src tests && mypy src

Procedimiento de publicación

Actualizar el número de versión (pyproject.toml)
Actualizar el historial de cambios (CHANGELOG.md)
Ejecutar las pruebas y confirmar que sean exitosas

Verificación de calidad del código:

black src tests
ruff check src tests
mypy src

Enviar a GitHub:

git add .
git commit -m "Release v0.1.0"
git tag v0.1.0
git push origin main --tags

Crear notas de versión en GitHub (opcional)

Preguntas frecuentes

P: ¿Puedo usar múltiples entornos kintone al mismo tiempo?

R: Sí, puede definir múltiples instancias de servidor en la configuración del cliente MCP. Asigne nombres diferentes a cada entorno (ejemplo: kintone-prod, kintone-dev).

P: ¿Puedo obtener información de campos en idiomas distintos del japonés?

R: Sí, puede obtener información de campos en inglés (en), chino (zh), español (es), etc., utilizando el parámetro lang en la herramienta get_form_fields.

Autor

r3-yamauchi

Licencia

Este proyecto se publica bajo la licencia MIT. Consulte el archivo LICENSE para más detalles.

Riesgos de usar el servidor MCP

Tenga siempre en cuenta que existe un cierto riesgo al usar servidores MCP creados e implementados por otras personas.

Estado actual del kintone AI Lab y el servidor 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 que ocurran en su propio entorno.