0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@rex0220

VSCode の Claude Code で kSQL MCP サーバーを使って kintone を SQL で操作する

0
Last updated at Posted at 2026-06-15

はじめに

Claude Code は、Anthropic が提供する CLI / IDE 拡張型の AI コーディングエージェントです。MCP（Model Context Protocol）サーバーを登録すると、Claude が外部ツールを「ツール」として直接呼び出せるようになります。

この記事では、kintone を SQL ライクに操作できる kSQL の MCP サーバー（ksql-mcp.js）を VSCode の Claude Code から利用する手順を、実例とあわせて紹介します。

ゴールは次のとおりです。

  • Claude Code に kSQL MCP サーバーを登録する
  • 自然言語の指示で kintone アプリのデータを SQL 取得・集計・グラフ化する

関連記事

前提環境

項目 バージョン例
OS Windows 11
Node.js v24 系（v18 以上推奨）
VSCode 最新版
Claude Code 拡張 インストール済み・ログイン済み
ksql-mcp.js 配布された MCP サーバー本体（単一 JS ファイル）
ksql.config.json 接続先・認証情報の設定ファイル

Node.js が入っているかは node --version で確認できます。

kSQL MCP サーバーとは

ksql-mcp.js は、kintone を SQL 風のクエリ（kSQL）で操作するための stdio 型 MCP サーバーです。Claude Code から呼び出すと、以下のようなツールが使えるようになります。

ツール名 役割
ksql_query SELECT / WITH / JOIN / SHOW APPS / DESCRIBE など読み取り系クエリの実行
ksql_mutate INSERT / UPDATE / DELETE など更新系（安全制御つき）
ksql_validate kintone API を呼ばずに kSQL を検証
ksql_explain 実行計画の確認
ksql_describe_app アプリのフィールド定義取得（DESCRIBE APPxxx）
ksql_show_apps アプリ一覧の取得（SHOW APPS）
ksql_save_query ほか クエリの保存・一覧・取得・実行・削除

セットアップ手順

以下では手順を 1 つずつ説明しますが、この登録作業自体を Claude Code に依頼してしまうこともできます。Claude Code はターミナルを操作できるため、ksql-mcp.js の場所と接続先を伝えれば、claude mcp add の実行から接続確認（claude mcp list）までまとめてやってくれます。

たとえば、次のように頼むだけです。

ksql\ksql-mcp.js の MCP サーバーを Claude Code で使えるように設定して

Claude Code が ksql-mcp.js の起動方法（--config / --profile オプション）を確認し、適切なスコープと絶対パスで登録 → 接続状態の確認まで実施します。仕組みを理解したうえで任せると安心です。以降では、その中身を手動で行う手順を説明します。

1. ファイルを配置する

任意のフォルダに ksql-mcp.js と ksql.config.json を置きます。本記事では以下を例にします。

C:\Users\<you>\Projects\work\ksql\
├── ksql-mcp.js
└── ksql.config.json

ksql-mcp.js は GitHub リポジトリの release フォルダから取得できます。

コマンドでダウンロードする場合は、Raw URL を指定します。

# PowerShell
curl.exe -L -o ksql-mcp.js https://raw.githubusercontent.com/rex0220/kintone-sql-tools/main/release/ksql-mcp.js

# bash / WSL
curl -L -o ksql-mcp.js https://raw.githubusercontent.com/rex0220/kintone-sql-tools/main/release/ksql-mcp.js

ブラウザで取得する場合は、上記の GitHub 上のファイルページ右上の Raw ボタンから保存してください。

2. 設定ファイル（ksql.config.json）を用意する

接続先 kintone のドメインや認証情報を ksql.config.json に記述します。複数環境を profiles として定義し、defaultProfile で既定を指定できます。

{
  "mcp": {
    "savedQueries": { "path": ".ksql/queries.json" }
  },
  "defaultProfile": "dev",
  "profiles": {
    "dev": {
      "baseUrl": "https://example.cybozu.com",
      "auth": "userpass",
      "username": "YOUR_USERNAME",
      "password": "YOUR_PASSWORD",
      "format": "table",
      "maxRecords": 10,
      "timeout": 3000
    },
    "guest": {
      "baseUrl": "https://example.cybozu.com",
      "guestSpaceId": 15,
      "auth": "userpass",
      "username": "YOUR_USERNAME",
      "password": "YOUR_PASSWORD",
      "format": "table",
      "maxRecords": 10,
      "timeout": 3000
    }
  }
}
キー 説明
baseUrl kintone のサブドメイン URL
guestSpaceId ゲストスペースを使う場合に指定
auth / username / password 認証方式と資格情報
maxRecords 既定の最大取得件数
timeout タイムアウト（ms）

:warning: パスワードが平文で入るため、Git 管理する場合は必ず .gitignore に追加してください。また、--scope project で使う .mcp.json やリポジトリ内の共有設定に、直接パスワードを書かないよう注意してください。

3. 動作確認（任意）

サーバー単体で起動できるかを確認します。

node ksql-mcp.js --help

次のように表示されれば OK です。

ksql-mcp - MCP server for kintone-sql-tools

Usage:
  ksql-mcp [options]

Options:
  --config <path>    Config file path (default: ./ksql.config.json or KSQL_CONFIG)
  --profile <name>   Default profile name
  -h, --help         Show help

4. Claude Code に MCP サーバーを登録する

VSCode の統合ターミナルで claude mcp add を実行します。設定ファイルは絶対パスで渡しておくと、起動ディレクトリに依存せず確実に読み込めます。

:warning: --scope などの Claude Code 側のオプションは、サーバー名 ksql より前に指定します（公式ドキュメント準拠）。

stdio 型 MCP サーバーとして登録する例です。

claude mcp add --scope local ksql -- node \
  "C:/Users/<you>/Projects/work/ksql/ksql-mcp.js" \
  --config "C:/Users/<you>/Projects/work/ksql/ksql.config.json"

--transport stdio を明示する場合は次のようにします。

claude mcp add --transport stdio --scope local ksql -- node \
  "C:/Users/<you>/Projects/work/ksql/ksql-mcp.js" \
  --config "C:/Users/<you>/Projects/work/ksql/ksql.config.json"

Windows の VSCode 統合ターミナル（PowerShell）では、\ は行継続になりません。複数行で書くときは行継続にバッククォート ` を使います。

claude mcp add --scope local ksql -- node `
  "C:/Users/<you>/Projects/work/ksql/ksql-mcp.js" `
  --config "C:/Users/<you>/Projects/work/ksql/ksql.config.json"

1 行で書く場合はこちら（最も確実）。

claude mcp add --scope local ksql -- node "C:/Users/<you>/Projects/work/ksql/ksql-mcp.js" --config "C:/Users/<you>/Projects/work/ksql/ksql.config.json"
  • ksql … MCP サーバーの登録名（任意）
  • --scope local … 現在の作業フォルダに紐づくローカル設定。認証情報を含む構成では推奨
  • -- 以降 … 実際に起動するコマンド
  • --profile <name> を末尾に足すと既定プロファイルを上書きできます

スコープの違い

スコープ 保存先 適用範囲
local ~/.claude.json（プロジェクトパス配下） 現在の作業フォルダに紐づくローカル設定。他のプロジェクトからは見えない
user ~/.claude.json（ユーザー設定） すべてのプロジェクト
project .mcp.json（リポジトリ内） チームで共有。設定ファイルに認証情報を含めないよう注意

local の設定自体は ~/.claude.json に保存されますが、登録したプロジェクト（作業フォルダ）でのみ読み込まれ、他のプロジェクトからは見えません。

5. 登録結果を確認する

claude mcp list

次のように ✓ Connected と表示されれば接続成功です。

ksql: node .../ksql-mcp.js --config .../ksql.config.json - ✓ Connected

6. Claude Code を再起動する

MCP サーバーはセッション開始時に接続されます。登録後は VSCode の Claude Code セッションを開き直してください。セッション内で /mcp を実行すると、接続状態と利用可能なツール一覧を確認できます。

使ってみる

あとは自然言語で指示するだけです。Claude が適切な kSQL ツールを選んで実行してくれます。

例 1: アプリ一覧とフィールド定義

SHOW APPS を実行してアプリ一覧を見せて
APP89 のフィールド定義を教えて

例 2: データ取得

APP100 のデータを取得して

実行されるクエリ（イメージ）:

SELECT * FROM APP100

実行例: アプリ結合 + 集計 + グラフ化

「顧客管理（APP89）と案件管理（APP88）を結合して、顧客ランク別に金額を集計してグラフにして」のように、結合・集計・可視化までまとめて依頼できます。VSCode の Claude Code で実際に実行したプロンプトがこちらです。

APP89 と APP88 を結合して、顧客ランク別の金額を集計してグラフ表示して

Claude は内部で次のような kSQL を組み立てて ksql_query を実行します。

SELECT a.顧客ランク, COUNT(*) AS 案件数, SUM(b.合計費用) AS 合計金額
FROM APP89 a
JOIN APP88 b
  ON a.レコード番号 = b.顧客管理レコード番号_関連レコード紐付け用
GROUP BY a.顧客ランク
ORDER BY 合計金額 DESC

Claude Code の回答

2026-06-15_16h29_46.png

集計結果は次のとおりです。

顧客ランク 案件数 合計金額 (円)
B 3 8,500,000
C 2 6,000,000
A 4 4,400,000

作成されたグラフ

Claude に「グラフにして」と頼めば、Chart.js を使った HTML を生成してブラウザで表示する、といった一連の作業も自動で行ってくれます。

2026-06-15_16h33_20.png

集計時はデフォルトの maxRecords（例: 10）で取得件数が制限され、結果がずれることがあります。全件を対象にしたい場合は「最大 500 件で集計して」のように件数を指定すると、ツールの maxRecords 引数に反映されます。

更新系クエリの安全制御

ksql_mutate（INSERT / UPDATE / DELETE）には誤操作防止の仕組みがあり、allowDml: true・confirmText: "yes"・dmlMaxRows の明示が必要です。読み取りと違い、意図しない一括更新が起きにくいように設計されています。

トラブルシューティング

症状 対処
claude mcp list で接続されない node ksql-mcp.js --help が通るか、パスが正しいかを確認
claude mcp add が失敗する --scope などのオプションをサーバー名 ksql より前に置いているか確認
ツールが出てこない MCP はセッション開始時に接続。Claude Code を再起動し /mcp で確認
認証エラー ksql.config.json の baseUrl / username / password を確認
別環境に接続したい --profile <name> で切り替え、または config の defaultProfile を変更
取得件数が少ない maxRecords の指定を増やす

まとめ

  • claude mcp add で ksql-mcp.js を登録するだけで、Claude Code から kintone を SQL 操作できる
  • 認証情報を含むため --scope local + 絶対パス指定が安全
  • 登録後は Claude Code を再起動して /mcp で確認
  • 自然言語の指示で「取得 → 結合 → 集計 → グラフ化」まで一気通貫で行える

kintone のデータ分析・運用が一段とスムーズになります。ぜひお試しください。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?