Claude kintone連携ガイド — 公式MCPサーバーの導入手順

サイボウズは2025年、kintoneの公式ローカルMCPサーバーをOSSとして公開しました。npmパッケージ・Dockerイメージ・Claude Desktop用のMCPBパッケージの3方式で配布されています。Claude CodeとClaude Desktopのどちらからも、アプリ情報の取得、レコードの追加・更新・削除、フォーム設定の変更まで自然言語で指示できます。

kintone MCPサーバーとは何か

kintone MCPサーバーは、サイボウズがApache 2.0ライセンスで公開する公式OSSです。cybozu developer networkの説明では、MCPサーバーに対応した生成AIツール(例:Claude Desktop)と組み合わせて使います。「生成AIからkintoneを操作できる」というのが、このサーバーの位置づけです。コードとドキュメントの一次情報源は、GitHubのkintone/mcp-serverリポジトリです。

サポート窓口はAPIサポートの対象外で、バグ報告や機能要望はGitHub Issuesで受け付ける運用です。業務でチーム導入する場合は、困ったときの問い合わせ先がkintoneのサポートではない点を先に共有しておくと、導入後の期待値がずれません。

OSSとして公開した狙いは、「生成AIとkintone、さまざまなサービスとの連携を柔軟に試せるようにするため」とされています。技術者がコードを自由に変更できるので、個別のユースケースにも合わせやすくなります。同じ国産グループウェアのLINE WORKSは、コミュニティ製サーバー経由で対応する形です。比較したい場合はClaude LINE WORKS連携をMCPで実現する方法を参照してください。

用意されているツールは26個です。アプリ情報・フィールド設定・フォームレイアウトの取得と変更、レコードの取得・追加・更新・削除、レコードコメントの追加、添付ファイルのダウンロードがあります。プロセス管理設定と一般設定の取得、動作テスト環境でのアプリ作成と運用環境への反映、スペースの作成・更新・削除も含まれます。

最新のツール一覧はGitHubリポジトリのREADMEが正です。

配布方式と認証方式は状況で選ぶ

導入前に決めることは2つあります。どの配布方式で動かすかと、どの認証でkintoneに入るかです。どちらも、読者の環境で答えが変わります。

認証方式はユーザー名・パスワードとAPIトークンの2種類で、どちらか一方が必須です。

APIトークンは英数字だけで構成される必要があり、10個以上を渡すと形式エラーになります。個人で試すだけならパスワード認証が早く、複数人で使うならアプリ単位で絞れるAPIトークンのほうが管理しやすくなります。

認証の上に重ねる設定が3つあります。kintone環境にBasic認証がかかっているなら、KINTONE_BASIC_AUTH_USERNAMEとKINTONE_BASIC_AUTH_PASSWORDを併用します。クライアント証明書認証を使うなら、PFXファイルのパスとパスワードを渡し、URLのドメインは.s.cybozu.comにします。通常の.cybozu.comではクライアント証明書認証が使えません。

社内プロキシを経由する環境では、HTTPS_PROXY環境変数を設定します。認証付きプロキシならhttp://username:password@proxy.example.com:8080の形で資格情報を埋め込めます。これはkintone MCPサーバー側の設定なので、サーバープロセスに渡る環境変数として指定します。

Claude Codeに追加する

Claude Codeへの追加はclaude mcp addで行います。kintone MCPサーバーはローカルで起動するstdioサーバーなので、--のあとにnpxコマンドを渡します。コマンドの全体像はclaude mcp addコマンドの解説にあります。

claude mcp add kintone \
  --env KINTONE_BASE_URL=https://example.cybozu.com \
  --env KINTONE_USERNAME=your-username \
  --env KINTONE_PASSWORD=your-password \
  -- npx -y @kintone/mcp-server

Dockerで動かす場合は、docker runにも-eで変数名を渡す点に注意します。

claude mcp add kintone \
  --env KINTONE_BASE_URL=https://example.cybozu.com \
  --env KINTONE_API_TOKEN=your-api-token \
  -- docker run -i --rm \
     -e KINTONE_BASE_URL -e KINTONE_API_TOKEN \
     ghcr.io/kintone/mcp-server:latest

登録が通ると、Claude Code v2.1.287ではAdded stdio MCP server kintoneで始まる1行が表示されます。--scope projectを付けた手元の確認では、プロジェクト直下の.mcp.jsonが次の内容で生成されました。

{
  "mcpServers": {
    "kintone": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kintone/mcp-server"],
      "env": {
        "KINTONE_BASE_URL": "https://example.cybozu.com",
        "KINTONE_API_TOKEN": "${KINTONE_API_TOKEN}"
      }
    }
  }
}

claude mcp get kintoneの出力は、同じ確認で次のとおりでした。

kintone:
  Scope: Project config (shared via .mcp.json)
  Status: ⏸ Pending approval (run `claude` to approve)
  Type: stdio
  Command: npx
  Args: -y @kintone/mcp-server

Statusが✔ ConnectedではなくPending approvalになっている点が肝心です。projectスコープで書いた.mcp.jsonのサーバーは、claudeを対話で起動して承認するまで接続もヘルスチェックもされません。チームの誰かが設定をコミットしても、各メンバーが自分の環境で承認する必要があります。.claude/settings.jsonで承認済みにしてコミットした場合も、信頼していないフォルダでは無視されます。承認後にclaude mcp listを見ると、✔ Connectedのような状態が出ます。セッション内の/mcpパネルでも同じ状態を確認できます。

スコープはどれを選ぶか

MCP設定にはlocal・project・userの3スコープがあり、kintone連携でも選び方で挙動が変わります。

• local(既定): 追加したプロジェクトだけで有効で、自分専用です。設定は~/.claude.jsonにプロジェクトのパスごとに保存されます
• project: .mcp.jsonに書かれ、バージョン管理でチームに共有できます。前述の承認が要ります
• user: すべてのプロジェクトで有効です。複数のプロジェクトからkintoneを触るなら向きます

プロジェクトで共有する場合、.mcp.jsonにトークンの実値を書かないことが前提です。上の出力のように${KINTONE_API_TOKEN}と書けば、各自の環境変数から値が入ります。${VAR}の展開はenvのほかcommand・argsでも効きます。ただし変数が未設定でデフォルト値もないと、サーバーは${VAR}という文字列のまま起動され、claude mcp listに警告が出ます。起動したのに認証が通らないときは、変数が展開されているかを疑います。

サーバーの信頼性評価や権限の絞り方といったMCP全般のセキュリティ判断は、MCPセキュリティガイドにまとめています。

なお、ローカルプロセスとして動く性質は、定期実行との相性にも影響します。日報や週報の自動化を考えている場合は、Cowork連携の現実的な進め方で可否を整理しています。

Claude Desktopで使う

MCPBパッケージのドラッグ&ドロップが最短です。GitHubのリリース一覧からkintone-mcp-server.mcpbをダウンロードし、Claude Desktopの「設定」→「デスクトップアプリ」→「拡張機能」ページにドロップします。インストール確認ダイアログで「インストール」を選ぶと、ベースURL・ユーザー名・パスワードを入れる設定ダイアログが開きます。ここで完結し、設定ファイルの編集は要りません。

設定ダイアログで必須なのはベースURLだけです。READMEの手順はユーザー名とパスワードを例に挙げています。ただしパッケージの定義(manifest.json)には、APIトークン・Basic認証・PFX・プロキシ・添付ファイルの保存先の欄もあります。MCPBのままAPIトークンで動かせます。設定ファイルで管理したい場合は、npmまたはDockerを使います。claude_desktop_config.jsonの書き方に沿って、mcpServersへ追記します。設定ファイルの形はClaude Codeの.mcp.jsonとほぼ同じで、片方を作ってからもう片方へ移植する進め方もできます。

Claude Code側のサーバーをDesktopに持っていくのではなく、逆向きの取り込みには専用コマンドがあります。claude mcp add-from-claude-desktopは、Claude Desktopの設定からサーバーを選んでClaude Codeへ取り込みます。macOSとWSLで使えます。

つまずいたときは症状から切り分ける

kintone MCPサーバー側のエラー文言は、GitHubの認証設定ガイドに原文が載っています。画面に出た文言と照らし合わせると、原因を絞りやすくなります。

証明書まわりには専用のエラーもあります。PFXのパスとパスワードの片方だけを設定すると、次の文言が出ます。Both KINTONE_PFX_FILE_PATH and KINTONE_PFX_FILE_PASSWORD must be provided together。両方を設定するか、両方とも消します。クライアント証明書を使っているのに認証が通らない場合は、.s.cybozu.comのドメインを使っているかも確認します。

できないことを先に知っておく

README記載の制限は、実際に指示を出す前に頭に入れておくと手戻りを減らせます。

レコード操作には、ゲストスペース以外にも2つの制限があります。1つ目は、レコードの登録・更新ツールでは添付ファイルフィールドを指定できないことです。ファイルを取得するkintone-download-fileはありますが、レコードにファイルを付ける向きの操作はできません。2つ目は、ユーザー選択・組織選択・グループ選択の各フィールドです。選択肢を設定している場合に限り、登録・更新ができます。

kintone-download-fileを使う場合は、--attachments-dir(またはKINTONE_ATTACHMENTS_DIR)の指定が必須です。指定しないとツール実行時にエラーになります。存在しないディレクトリを指定した場合は、新規作成されてから保存されます。

もう1点、通信の行き先も押さえておきます。このMCPサーバーが接続するのはkintone REST APIで、利用地域ごとのプライバシーポリシーはリポジトリのPRIVACY.mdにまとまっています。

よくある質問

kintone MCPサーバーはClaude以外のツールでも使える?

使えます。READMEにはCursor向けのインストールリンクがあり、設定ファイルの例も.cursor/mcp.jsonが挙がっています。MCPに対応したクライアントなら、同じサーバーを共有できます。

kintoneのプラグインやJavaScriptカスタマイズも生成できる?

ツール一覧を見る限り、プラグインやJavaScriptカスタマイズのコード生成を担うツールはありません。サーバーが担当するのはアプリ設定・レコード・スペースの操作です。コードはClaude Codeに書かせ、動作確認用のテストアプリの作成とデプロイをkintone MCPサーバーに任せる組み合わせが考えられます。具体的なレコードの検索・更新は、kintoneレコード検索・更新の実践ガイドが扱っています。

まとめ

試す段階ならユーザー名・パスワードとnpxの組み合わせが最短で、チームで共有するならAPIトークンと.mcp.jsonの${VAR}参照が基本形です。projectスコープは各自の承認が要るので、接続できないときは認証より先にStatusを見ると早く片付きます。