Overview

The Kintone MCP Server is a local Model Context Protocol (MCP) server that exposes kintone (Cybozu) APIs to MCP-compatible clients (for example, Claude Desktop or other local LLM toolchains). It lets developers run a lightweight, locally-hosted service that proxies authenticated requests to a kintone instance and exposes a predictable MCP interface for integrations, testing, and local workflows.

This server is useful for local development, automated testing, and quick prototyping where you need an MCP-compatible bridge to kintone without deploying code to cloud environments. You can run it as a standalone Node package, a Docker container, or install it as an MCPB package inside Claude Desktop / other MCP clients.

Features

Exposes kintone endpoints via the Model Context Protocol (MCP).
Multiple distribution formats: MCPB package, Docker image, npm package.
Environment-variable and CLI-configurable authentication and base URL.
Simple configuration file support for advanced settings (proxy, timeouts, tools).
Includes helper tools for common tasks (e.g., file download helper for kintone attachments).
Works offline for local tooling while proxying only needed API calls to kintone.

Installation / Configuration

Choose one of the following installation methods.

1) Install as MCPB (for Claude Desktop)

Download the latest kintone-mcp-server.mcpb from the releases page:
- https://github.com/kintone/mcp-server/releases
Open Claude Desktop → Settings → Desktop App → Extensions.
Drag & drop the downloaded .mcpb file into the extension area and follow the install prompts.
Enter the required settings in the extension dialog:
- Kintone Base URL: https://example.cybozu.com
- Kintone Username
- Kintone Password

2) Run with Docker

Prerequisite: Docker installed.

Run with environment variables:

docker run -i --rm \
  -e KINTONE_BASE_URL=https://example.cybozu.com \
  -e KINTONE_USERNAME="myuser" \
  -e KINTONE_PASSWORD="mypassword" \
  ghcr.io/kintone/mcp-server:latest

Or with Docker Compose (example):

version: "3.8"
services:
  kintone-mcp:
    image: ghcr.io/kintone/mcp-server:latest
    environment:
      KINTONE_BASE_URL: "https://example.cybozu.com"
      KINTONE_USERNAME: "myuser"
      KINTONE_PASSWORD: "mypassword"
    ports:
      - "3000:3000"

3) Install as npm CLI

Prerequisite: Node.js (and optionally pnpm) installed.

Global install:

npm install -g @kintone/mcp-server

Run via CLI:

kintone-mcp-server \
  --base-url https://example.cybozu.com \
  --username myuser \
  --password mypassword

You can also use environment variables in place of CLI flags:

Env variable	CLI flag
KINTONE_BASE_URL	–base-url
KINTONE_USERNAME	–username
KINTONE_PASSWORD	–password

Configuration file example

You can supply a JSON configuration file for advanced options (proxy, tools, timeouts). Example mcp-server.config.json:

{
  "baseUrl": "https://example.cybozu.com",
  "username": "myuser",
  "password": "mypassword",
  "port": 3000,
  "proxy": {
    "host": "http://proxy.example.local:3128",
    "noProxy": ["localhost", "127.0.0.1"]
  },
  "timeoutMs": 30000
}

Start with a config file:

kintone-mcp-server --config ./mcp-server.config.json

Generating Cursor install links (pnpm doc:cursor-install-link)

The repository includes a helper task to produce Cursor (or other deeplink) install links. To generate the Cursor install link:

Install dependencies with pnpm:

pnpm install

Run the doc task:

pnpm doc:cursor-install-link

This prints (or writes) a JSON/deeplink string that you can use to create an install badge or a one-click installation URL for Cursor. Example output (truncated):

{
  "command": "docker",
  "env": { "KINTONE_BASE_URL": "...", "KINTONE_USERNAME": "..."},
  "args": ["run","-i","--rm","ghcr.io/kintone/mcp-server:latest"]
}

Use that output as a deeplink or embed it into Cursor’s install URL to let users install the MCP server inside Cursor in one action.

Available Tools / Resources

Included or linked helper tools (available inside the repo or server distribution):

kintone-download-file — fetch and stream files attached to kintone records (note: requires correct permission scope).
CLI helpers to list available endpoints and debug requests.
Docker images on GitHub Container Registry: ghcr.io/kintone/mcp-server.
Releases page with .mcpb packages for MCP clients.

Use Cases

Local development: Provide a stable MCP endpoint that replicates your kintone setup for plugin development or chat-based queries without exposing production credentials widely.
Testing & CI: Spin up the Dockerized MCP server in CI to run integration tests that need kintone API access.
Prototyping with LLM tools: Install the MCPB in Claude Desktop (or use Cursor deeplink) to let a local LLM access kintone records safely through the MCP bridge.
File retrieval automation: Use the kintone-download-file helper to pull attachments for local processing or indexing.

Troubleshooting & Tips

Connection errors: verify KINTONE_BASE_URL correctness and network/proxy settings. Use the proxy entry in the config file or set standard env vars (HTTP_PROXY / NO_PROXY).
Authentication errors: confirm username/password and account permissions. If SSO or more advanced auth is used, create an application-specific user or API token where possible.
Permission errors: check the kintone user’s app permissions and record-level access. File download tools may require additional read attachments permission.

If you need to customize behavior (timeouts, ports, proxy bypass), use the JSON config and the CLI flags together — flags take precedence over the config file.

License & Support

The project is open source (Apache 2.0). For issues, feature requests, or contributions, open an issue or PR on the GitHub repository: https://github.com/kintone/mcp-server.

Kintone MCP Server Installation and Configuration