kintone MCP完全攻略 — AAAグレードの真相と3認証方式、エージェント開発の落とし穴
CybozuのkintoneはKanseiLink AEO評価でAAAグレードを獲得している数少ない日本発SaaSの1つだ。公式MCPサーバーはnpm・Docker・Desktop Extensionの3形式で提供され、2026年3月にはプロセス管理APIとDesktop Extensionが追加された。しかしkintone APIには、エージェント開発者が必ずハマる独特の仕様がある。本記事ではKanseiLinkの実データをもとに、AAAグレードの根拠・3つの認証方式の使い分け・実装時の5つの落とし穴を徹底解説する。
1. なぜkintoneはAAAグレードなのか
認証: APIトークン / パスワード / OAuth 2.0
最終更新: 2026-04-13
KanseiLinkがkintoneにAAAを付与している根拠は以下の3点だ。
| 評価軸 | kintoneの実績 | 評価 |
|---|---|---|
| 公式MCPサーバー | Cybozu公式（github.com/kintone/mcp-server）、npm・Docker・Desktop Extension対応 | ✅ 最高水準 |
| 認証方式の多様性 | APIトークン（シンプル）、パスワード認証、OAuth 2.0の3方式をサポート | ✅ 優秀 |
| API成熟度 | RESTful API v1、ページネーション・バルク操作・プロセス管理API完備 | ✅ 優秀 |
| アップデート頻度 | 2026年3月にプロセス管理API（3/30）・Desktop Extension（3/10）を追加 | ✅ 積極的 |
| ドキュメント品質 | cybozu.dev で日英の公式ドキュメントが整備済み | ✅ 良好 |
一方で、trust_scoreは0.7（満点1.0）に留まる。理由はkintone固有のAPI仕様（後述する{value}ラッパーやフィールドコードの問題）がエージェントの初回実装を困難にするためだ。AAA評価は「エコシステムとしての完成度」であり、「すぐに使える簡単さ」ではない点に注意が必要だ。
2. 3つの認証方式 — どれを選ぶべきか
kintoneは3種類の認証方式をサポートする。エージェント開発の用途別に使い分け方を解説する。
① APIトークン認証
最もシンプルな認証方式。kintoneアプリごとにトークンを発行し、X-Cybozu-API-Token ヘッダーに設定するだけで動作する。OAuthのような複雑なフローが不要なため、エージェント実装に最適。
- 1 kintone管理画面 → アプリ設定 → APIトークン → 「追加」
- 2 必要な権限（レコード閲覧・追加・編集）にチェックを入れてトークン生成
- 3
X-Cybozu-API-Token: {generated_token}ヘッダーでリクエスト - 4 複数アプリを操作する場合はトークンをカンマ結合：
token1,token2
② パスワード認証（Basic認証）
ユーザー名とパスワードをBase64エンコードして X-Cybozu-Authorization ヘッダーに設定する方式。本番環境での使用は推奨されないが、開発時の素早いテストには便利。
- 1
username:passwordをBase64エンコード - 2
X-Cybozu-Authorization: {base64_string}ヘッダーを設定 - 3 ※本番では必ずAPIトークンまたはOAuthに切り替えること
③ OAuth 2.0認証
最も安全な認証方式。ユーザーのアクセス権限をきめ細かく制御できる。スコープ：k:app_record:read、k:app_record:write。エンタープライズ向けアプリや複数ユーザーが使うシステムに適する。
- 1 developer.cybozu.ioでOAuthアプリを登録
- 2 Authorization URL:
https://{subdomain}.cybozu.com/oauth2/authorization - 3 Token URL:
https://{subdomain}.cybozu.com/oauth2/token - 4 スコープに
k:app_record:read k:app_record:writeを指定
3. エージェント開発者が必ずハマる5つの落とし穴
kintone APIの最大の罠。レスポンスの全フィールド値はオブジェクト形式 {"value": "実際の値"} でラップされている。数値フィールドも文字列フィールドも例外なし。record.タイトル ではなく必ず record.タイトル.value でアクセスすること。
// kintone GET /k/v1/record.json のレスポンス
{
"record": {
"$id": { "value": "42" }, // IDも文字列のvalue
"タイトル": { "value": "プロジェクトA" }, // ✅ .value でアクセス
"数量": { "value": "100" }, // 数値も文字列として返る！
"担当者": {
"value": [{ "code": "user1", "name": "山田太郎" }]
}
}
}
// ❌ 間違い: record.数量 → undefined
// ✅ 正解: record.数量.value → "100" (文字列)
// ✅ 正解: parseInt(record.数量.value) → 100 (数値として使う場合)
kintoneはフィールドに「表示名」（例：「担当者名」）と「フィールドコード」（例：assignee_name）の2つの名前がある。API呼び出しでは必ずフィールドコードを使う。まず GET /k/v1/app/form/fields.json?app={app_id} でフィールドコード一覧を取得してからAPIを叩くこと。
// Step 1: フィールドコード一覧を取得
const fieldsRes = await fetch(
`https://${subdomain}.cybozu.com/k/v1/app/form/fields.json?app=${appId}`,
{ headers: { 'X-Cybozu-API-Token': apiToken } }
);
const { properties } = await fieldsRes.json();
// properties = { "タイトル": { type: "SINGLE_LINE_TEXT", code: "タイトル", label: "案件名" } }
// Step 2: フィールドコードでレコードを検索
const recordsRes = await fetch(
`https://${subdomain}.cybozu.com/k/v1/records.json?app=${appId}&query=ステータス%3D"進行中"&totalCount=true`,
{ headers: { 'X-Cybozu-API-Token': apiToken } }
);
const { records, totalCount } = await recordsRes.json();
console.log(`合計 ${totalCount} 件`); // totalCount: "42" (文字列)
kintone APIのベースURLは https://{subdomain}.cybozu.com の形式で、各企業のkintoneサブドメインが必要。APIドキュメントには固定URLが存在しない。エージェント実装では、ユーザーにサブドメインを入力してもらうか、環境変数 KINTONE_SUBDOMAIN で事前設定するフローが必須。
標準プランでは1日あたり10,000リクエスト制限がある。エージェントが大量のレコードを処理する場合、バルク操作（POST /records.json で最大100件一括登録）を活用して1リクエストあたりの処理量を増やすことが必須。また、同時接続数は10に制限されているため、並列処理の上限に注意。
1件ずつPOSTするのではなく、配列で最大100件まとめてPOSTすること。10,000リクエスト/日の制限内で最大100万件/日の操作が可能になる。
// ✅ バルク登録（最大100件）
const records = Array.from({ length: 100 }, (_, i) => ({
タイトル: { value: `タスク${i + 1}` },
ステータス: { value: "未着手" },
}));
const res = await fetch(
`https://${subdomain}.cybozu.com/k/v1/records.json`,
{
method: 'POST',
headers: {
'X-Cybozu-API-Token': apiToken,
'Content-Type': 'application/json',
},
body: JSON.stringify({ app: appId, records }),
}
);
// → { "ids": ["1","2",...,"100"], "revisions": ["1","1",...,"1"] }
kintoneのクエリ構文はSQLに似ているが独自仕様。文字列値は必ず二重引用符で囲む（ステータス = "進行中"）、スペースはそのままでOK、URLエンコードが必要、totalCount: true を指定しないと総件数が返らない。ORDER BY・LIMIT・OFFSETも使えるため、ページネーション実装に活用できる。
// ページネーション（100件ずつ取得）
`/k/v1/records.json?app=${appId}&query=ステータス%20%3D%20"進行中"%20order%20by%20更新日時%20desc%20limit%20100%20offset%200&totalCount=true`
// 複合条件
`query=ステータス%20%3D%20"完了"%20and%20担当者%20in%20("user1")%20and%20期限%20%3C%20"2026-04-30"`
// 注意点：
// - 文字列値は "二重引用符" で囲む（シングルクォート不可）
// - in演算子: field_code in ("val1", "val2")
// - totalCount=true を付けないと totalCount が返らない
// - デフォルトlimit=100、最大limit=500
4. Garoonとの連携 — Cybozuデュアルスタックの力
kintoneとGaroon（同じCybozu製のグループウェア）は、同一のAPIトークン認証とX-Cybozu-API-Tokenヘッダー形式を共有している。これにより、1つのエージェントがkintoneでレコード管理を行いながら、Garoonでスケジュール確認・ワークフロー承認を同時に操作する「Cybozuデュアルスタック」が自然に実現できる。
| 機能 | kintone MCP | Garoon MCP |
|---|---|---|
| レコード管理（CRM・案件管理など） | ✅ /k/v1/records.json | — |
| スケジュール・カレンダー | — | ✅ /g/api/v1/schedule/events |
| ワークフロー承認 | ✅ /k/v1/record/status.json（プロセス管理） | ✅ /g/api/v1/workflow/requests |
| 掲示板・社内周知 | — | ✅ /g/api/v1/bulletin |
| 認証方式 | APIトークン / OAuth2 | APIトークン（同形式） |
まとめ — kintoneはAAA、ただし準備が要る
kintoneのMCPエコシステムは日本SaaS中でも最も整備されたものの1つだ。公式MCPサーバーの3提供形態、3つの認証方式、バルク操作やプロセス管理APIまで揃ったAPIは、業務自動化の基盤として強力だ。
ただし、{value}ラッパーとフィールドコードという独自仕様への理解なしに始めると、最初の数時間で確実にハマる。本記事の落とし穴5点を事前に把握してから実装に入ることで、立ち上げ時間を大幅に短縮できるはずだ。
KanseiLinkでは今後、kintoneの実エージェント運用データ（成功率・レイテンシ・エラーパターン）が蓄積され次第、動的なスコア更新を実施する。最新のAEOスコアは以下のリンクで確認できる。