kintone のダッシュボードを、日本語の要件を伝えるだけで AI に作らせる環境を公開しました。
アプリ 4149(案件管理)の一覧「【全社】ダッシュボード」に、期間を切り替えられる
ダッシュボードを作って。
期間コントロールの選択肢は 今月・前月・今年・去年・期間指定。既定は今月。
ペインは、受注金額 KPI、フェーズ別売上の棒グラフ、受注予定の明細表の 3 枚。
すべて受注予定日で期間に追従させて。
settings/案件管理-期間ダッシュボード.json に保存して。
これだけで、AI が実アプリのフィールド定義と実データを確認しながら SQL を確定し、
プラグインにそのまま取り込める設定 JSON を書きます。あとはインポートして保存するだけです。
テンプレートリポジトリ(public): https://github.com/rex0220/ksql-dashboard-pro-authoring
プラグイン本体の機能(表示タイプ・設定画面・テーマ・タブなど)は
製品紹介記事 を、
SQL とペイン設定の実例集は SFA パック実践記事 を参照してください。
本記事は「AI に作らせる」環境の構築と使い方に絞ります。
仕組み
kSQL Dashboard Pro のダッシュボードは、設定 JSON のインポート/エクスポートで
まるごと受け渡しできます。そして同じ SQL エンジン(kintone-sql-tools)には
MCP サーバーが同梱されていて、AI エージェントが kintone を読み取り専用で
照会できます。この 2 つを組み合わせると、こうなります。
ポイントは ① です。AI は思い込みで SQL を書くのではなく、
ksql_describe_app でフィールドコードと型を確かめ、ksql_query で実データを見て、
返ってくる列名と件数を確認してから設定 JSON を書きます。
「フィールド名が 1 文字違いで動かない」「集計が取得上限を超えて動かない」といった
定番の事故を、作る前に潰せます。
生成した設定は settings/ のファイルとして残り、git で履歴管理できます。
「先週の版に戻す」「何を変えたか diff で見る」が、ダッシュボードでできるようになります。
前提
| 項目 | 本記事の前提 |
|---|---|
| プラグイン | kSQL Dashboard Pro Ver.1(有償。別途入手) |
| SQL エンジン / MCP | kintone-sql-tools 3.39.0(npm から自動で入ります) |
| Node.js | 20 以上 |
| エディター | VSCode + Claude Code(サブスクリプションが必要) |
| kintone アカウント | ログインユーザー認証を使います(2 要素認証なしのアカウント。閲覧専用アカウントがあればベスト) |
| 対象アプリ | 記事の例はアプリストア SFA(営業支援)パックの案件管理 |
AI が kintone に 書き込むことはありません。テンプレートは 3 層(AI への常設指示・
ツールの拒否設定・エンジンの承認ゲート)で読み取り専用を守ります。詳細はテンプレートの
README を参照してください。
環境構築(初回 10 分)
1. テンプレートから自分のリポジトリを作る
テンプレートページ右上の Use this template → Create a new repository で、
自分のアカウントに private で作成して clone します。
作成画面の visibility は Public が初期値です。必ず Private に切り替えてください。
設定 JSON にはアプリ番号・フィールド名・業務用語が入ります。GitHub CLI なら 1 行で確実です:
gh repo create ksql-dashboards --template rex0220/ksql-dashboard-pro-authoring --private --clone
2. 依存を入れる
npm install
SQL エンジンと MCP サーバーが入ります。これだけです。
3. 認証情報を置く
.env.example をコピーして .env を作り、接続先を書きます。
KSQL_BASE_URL=https://<自分の環境>.cybozu.com
ログイン名・パスワードは OS のユーザー環境変数に置くのがおすすめです
(プロジェクト内のファイルに残りません)。Windows ならコマンドプロンプトで:
setx KSQL_USERNAME "<ログイン名>"
setx KSQL_PASSWORD "<パスワード>"
を実行して、VSCode のウィンドウをすべて閉じて起動し直します
(「Reload Window」では反映されません — 筆者はここで一度つまずきました)。
反映確認は VSCode のターミナルで $env:KSQL_USERNAME と打ち、ログイン名が出れば OK。
手早く試すだけなら .env に KSQL_USERNAME / KSQL_PASSWORD の 2 行を足しても
動きます(.env は git 管理外です)。
4. VSCode で開いて Claude Code を起動
初回に kSQL MCP サーバーの使用可否を聞かれるので許可します。
以後、kintone の読み取りと settings/ へのファイル保存は確認なしで進みます
(テンプレート同梱の許可設定)。
5. 疎通確認
Claude Code にそのまま頼みます:
ksql_show_apps を実行して
アプリの一覧が返ってくれば準備完了です。
作らせる
事前準備: ダッシュボード専用の一覧(手作業・1 分)
AI は kintone の設定を変更できません(読み取り専用)。全面ダッシュボードを置く
カスタマイズ形式の一覧だけ、先に人が作っておきます。
- アプリの設定 → 一覧 → 「＋」で新規作成
- レコード一覧の表示形式を 「カスタマイズ」 にする(HTML は空のままでよい)
- 名前(例:
【全社】ダッシュボード)を付けて保存 → アプリを更新
指示する
冒頭の指示文を Claude Code に貼ります。コツは 3 つだけです。
-
アプリは番号で指定する(アプリの URL
/k/番号/の数字)。同名アプリの取り違え防止 - 置き場は一覧名で指定する(インポート時に一覧名で照合されます)
-
保存先のファイル名を指定する(
settings/◯◯.json に保存して)
すると AI は、おおむねこう動きます(全部自動です):
-
ksql_describe_app— 案件管理のフィールドコードと型を確認 -
ksql_query— 商談フェーズの実際の値や売上の実データを確認 -
SELECT COUNT(*)— 対象件数が取得上限に収まるかを確認 -
ksql_validate— 3 ペイン分の SQL を検証 -
settings/案件管理-期間ダッシュボード.jsonを生成(封筒形式)
生成された JSON の中身は、たとえば KPI ペインならこうなっています:
SELECT SUM(売上) AS メイン値
FROM APP4149
WHERE 商談フェーズ in ('受注')
AND 受注予定日 >= @period_from
AND 受注予定日 < @period_to_next
@period_from / @period_to_next は期間コントロールの変数です。閲覧者がバーで
「前月」や「期間指定」を選ぶと、この範囲が差し替わって全ペインが追従します。
こうした Pro 固有の書き方(半開区間・封筒形式・列名の規則など)は、テンプレートに
同梱した仕様書と AI への常設指示(CLAUDE.md)が押さえているので、利用者が覚える
必要はありません。
取り込む
- アプリの設定 → プラグイン → kSQL Dashboard Pro の 設定
- ヘッダーの ツール → インポート で生成された JSON を選択
- 確認ダイアログの「アプリ番号の変換」で、必要なら自分の環境の番号を入力
- 保存
検証に失敗した場合、既存の設定には一切触れません。エラー内容を AI に貼れば直します。
作った後 — 変更も AI に頼む
2 回目からは「対象ファイル名 + 変更内容 + 更新して」の形で頼みます。
settings/案件管理-期間ダッシュボード.json を更新して。
明細の表に、商談フェーズが「受注」の行を緑にする条件付き書式を追加。
期間コントロールに「今週」も足して。
- 変更は同じファイルへの上書きで返ってくるので、git の diff で「何が変わったか」を
確認してからインポートできます - 設定画面(GUI)で直した場合は、エクスポートした JSON を AI に渡して
「これを settings/ の正として上書きして」と頼めば、git 側が正に戻ります
指示文のパターン集(タブあり・共通サマリー・変更依頼・トラブル時)はテンプレートの
docs/指示レシピ例.md
にまとめてあります。
つまずいたら
| 症状 | 確認すること |
|---|---|
| MCP サーバーが起動しない | Node.js 20 以上か(node -v)。npm install 済みか。.env を作ったか |
AuthError: token is not resolved |
認証情報が届いていない。setx 後に VSCode を完全再起動したか(Reload Window では反映されません) |
| 401 / 権限エラー | ログイン名・パスワードの誤り。2 要素認証が有効なアカウントは使えません |
| アプリが見えない・少ない | そのユーザーにアプリの閲覧権限があるか |
| インポートで「出力元の情報がありません」 | AI に「封筒形式で出力し直して」と伝える |
| ペインが「取得上限に達したため中止しました」 | AI に「COUNT(*) で件数を確認して、期間で絞るか取得上限を上げて」と伝える |
まとめ
-
要件は日本語、確認は実データ、成果物は git 管理の設定 JSON。 ダッシュボード作りが
「設定画面での組み立て作業」から「要件を言葉にする作業」に変わります - テンプレートは public で公開しています。Use this template → private でどうぞ:
https://github.com/rex0220/ksql-dashboard-pro-authoring - プラグインの機能全般は 製品紹介記事、
SQL の実例集は SFA パック実践記事 へ