Kintone Data Orchestrator via MCP

Introduction

This repository supplies example code for an unofficial Model Context Protocol (MCP) server designed specifically for interfacing with Kintone. Kintone functions as a platform where essential work components, or tasks, are organized. This server permits MCP host applications, such as Claude Desktop, to reference, modify existing Kintone data, and even provision entirely new Kintone applications. Note that Cybozu has officially released a dedicated MCP Server; users without specific legacy requirements should generally opt for the official offering.

Setup via DXT File (Recommended for Claude Desktop)

Installation through the .dxt package is the preferred method for integration with Claude Desktop environments. First, retrieve the most recent release file from the official distribution point. Next, access the configuration section within your Claude Desktop application settings, navigating to the extensions management area. Select the option to install extensions and specify the path to the downloaded file. Subsequently, input the necessary Kintone domain, user credentials, and secret passkey to establish the connection and save the parameters. Finally, activate the newly installed extension toggle within the settings to enable its functionality for use in new chat sessions. You can verify operation by invoking a tool command related to Kintone data retrieval.

Alternative Setup Without DXT File

1. Source Code Acquisition

Clone or download the source repository content to a local directory. Ensure the chosen location path consists only of standard alphanumeric characters without spaces for optimal system compatibility.

2. Node.js Prerequisite

Confirm that Node.js version 20 or a newer iteration is successfully installed on your operational system.

3. Dependency Resolution

Execute the package manager command to fetch and install all required software dependencies.

npm i

4. Configuration File Modification

Locate the claude_desktop_config.json file within the application settings directory. You must augment the mcpServers object within this file, incorporating the necessary connection parameters as detailed below. This involves defining the execution command, environment variables for credentials, and the file path to the server's main script.

{
  "mcpServers": {
    "kintone": {
      "command": "node",
      "env": {
        "KINTONE_DOMAIN": "[Your Kintone Subdomain].cybozu.com",
        "KINTONE_USERNAME": "Username for MCP Access",
        "KINTONE_PASSWORD": "User password in plain text"
      },
      "args": [
        "[Path/to/kintone-mcp-server]/server.js"
      ]
    }
  }
}

5. Application Restart

After saving the configuration file changes, completely terminate the Claude Desktop application instance. Ensure it is not merely minimized but fully quit, potentially by closing any background processes from the system tray icon, before relaunching.

Usage Protocols

1. Initial Validation Test

To confirm proper communication, instruct the AI model to query the application ID for a specific Kintone application name accessible by your configured user. The exact naming convention used in the prompt must precisely match the record within Kintone to avoid task failure.

2. Supported Functionality Overview

This MCP server exposes a comprehensive set of tools for data interaction and administrative changes within Kintone. Consult the docs/tool-annotations.md file for detailed specifications regarding each tool's annotation attributes.

Record Manipulation

Operations include methods to retrieve single records, execute complex record searches, add new entries, modify existing data, perform upserts based on key fields, append comments, and alter record statuses or assignees within process management flows.

File Management

Functions are available for securely uploading files to Kintone and downloading files from records. Be aware that downloading very large files, exceeding approximately 1MB, might not function reliably with the current implementation.

Application Metadata Retrieval

This category allows inspection of application configurations, such as fetching lists of applications matching search terms, obtaining form layout definitions, retrieving plugin lists, accessing process management settings, and examining security permissions at various levels (application, field, record).

Application Configuration Management

Advanced functions permit the provisioning of new Kintone applications, adding or updating field definitions, modifying form layouts, altering general application settings, initiating deployment to production environments, and managing access controls or view configurations.

Space Management

Tools are provided for interacting with Kintone Spaces, allowing retrieval and modification of space settings, updating member lists, and managing associated threads and guest user access.

User and Group Information

Capability exists to query the Kintone user directory, retrieve group structures, and list members belonging to specified organizational groups.

Connection Verification

Utility methods allow retrieval of the currently configured Kintone domain and the username designated for the MCP connection.

Related Topics

• Task Dependency Management: Understanding how sequential work units can halt overall progress if prerequisites are not met.
• Project Life Cycle Phases: How the provisioning and modification of system structures (like Kintone apps) fit into larger project execution stages.
• Work Breakdown Structure (WBS): The hierarchical decomposition of project scope into manageable components, analogous to Kintone records and fields.
• Coordination of Effort: The mechanism required to combine multiple individual inputs effectively to achieve a collective organizational goal.

Extra Details

In project execution, a common pitfall arises when judging task completion status inaccurately. While a task might be mathematically close to finishing, practical completion often takes disproportionately longer than estimated ratios suggest. This server primarily manages the data structures supporting these tasks. Furthermore, system integration often necessitates careful management of access rights; the included tools for viewing and updating ACL (Access Control List) settings are vital for maintaining data governance within the Kintone environment.

Conclusion

This server acts as a crucial bridge, enabling sophisticated, automated management of work items stored within the Kintone environment via external AI agents. Efficiently coordinating data access and configuration changes supports the principle that successful project completion relies on linking detailed, granular activities (tasks) with the overarching requirements of the entire system structure.

This toolset is provided "as is," originating from generative AI creation. Please review the linked external blog posts for broader context regarding Kintone integration strategies and the current state of similar MCP server technologies. For remote access via standard web browsers or ChatGPT using OAuth, a separate repository provides relevant sample code.

Disclaimer: "Kintone" is a registered trademark belonging to Cybozu, Inc. This documentation is purely informational; individual support for configuration questions or operational failures in unique environments cannot be furnished.