dbhawk

DBHawk MCP — Claude Code プラグイン＋デモ用コネクター

AI アシスタントが DBHawk にアクセスできるようにします。ユーザーに割り当てられたデータソースの一覧表示、スキーマ／テーブル／カラムの参照、クエリの実行（ユーザーのアクセス制御とカラムマスキングが適用されます）、およびDBHawk AIによるテキストからの SQL 生成／最適化／整形が可能です。データやスキーマの変更は、ユーザーのMCP ティアで許可されている場合に限り可能です。デフォルトのティアは読み取り専用です（読み取り、書き込み、MCP ティアを参照）。

既存の DBHawk REST エンドポイント /api/v2/mcp/** を介する軽量なブリッジです。実行される内容はすべて DBHawk が決定します。すべてのステートメントは分類され、トークン所有者のロールにかかわらず、ユーザーのグループに設定されたティアに基づいてチェックされます。

サインイン、または個人用トークン。 DBHAWK_TOKEN を空のままにすると、最初のツール呼び出し時にサーバーがブラウザーを通じて DBHawk にサインインします。DBHawk のログインページが開き（パスワード、LDAP、2FA、SSO など、お使いの DBHawk で利用可能な方法）、一度アクセスを承認すると、サーバーは次回の起動に備えてユーザープロファイルにリフレッシュトークンを保存します（Windows では %APPDATA%\dbhawk-mcp、macOS では ~/Library/Application Support/dbhawk-mcp、Linux では ~/.config/dbhawk-mcp）。これには MCP コネクターを備えた DBHawk 7.0.1 が必要です。実行できる操作は、トークンを使う場合と同様に、MCP ティアによって決まります。UPGRADE-7.1.0.mdを参照してください。

個人用トークンを使う場合、認証は 2 段階です。 DBHAWK_TOKEN は個人用トークン（dbh_<id>.<secret>）であり、JWT ではありません。MCP エンドポイントはこれを直接受け付けません。最初の呼び出し時に、サーバーは個人用トークンを X-API-Token ヘッダーに指定して POST /api/v2/auth/token/exchange に送信し、有効期間の短い JWT と交換します。その JWT をキャッシュし、すべての /api/v2/mcp/** 呼び出しで Bearer として送信します。JWT の exp が切れる少し前に、サーバーはあらかじめ新しい JWT と交換します。それでも呼び出しが 401 を受け取った場合は、再交換して 1 回だけ再試行します。これらの処理はユーザーから見えません。

dbhawk-mcp-plugin/                 <- this folder = a Claude Code "marketplace" (push it to git)
├── .claude-plugin/marketplace.json
└── dbhawk/                        <- the actual plugin (installed by users)
    ├── .claude-plugin/plugin.json
    ├── .mcp.json                  <- declares the "dbhawk" stdio MCP server
    └── mcp-server/
        ├── index.js               <- source
        ├── package.json           <- build tooling (maintainers only)
        └── dist/dbhawk-mcp.mjs    <- COMMITTED self-contained bundle (what users run; no npm install)

dist/ にあるバンドルにはすべての依存関係が含まれているため、git clone するだけでインストール不要で実行できます。これにより /plugin install が動作します。

---

ユーザー向け — インストール

Claude Code（マーケットプレイスから）

このリポジトリが GitHub に公開されたら（下記の公開を参照）、Claude Code に指定してインストールします。

/plugin marketplace add datasparc/dbhawk-mcp-plugin
/plugin install dbhawk@dbhawk-marketplace

dbhawk はプラグイン名、dbhawk-marketplace はマーケットプレイス名（marketplace.json に記載）です。続いて接続を設定し（設定を参照）、/mcp でツールが利用可能になっていることを確認します。

Git ホストを使わずに試してみたい場合は、ローカルフォルダーを 1 回のセッションで読み込みます。

claude --plugin-dir ./dbhawk-mcp-plugin/dbhawk

Claude Desktop（拡張機能、.mcpb）— 推奨

Claude Desktop では、適切な GUI 設定フォーム（JSON の編集は不要）を備えたデスクトップ拡張機能としてインストールできます。これは同じ MCP サーバーを .mcpb バンドルにパッケージ化したものです。

1. リリースページから dbhawk-<version>.mcpb をダウンロードします。
2. Claude Desktop で、設定 → 拡張機能 → 詳細設定 → インストールを選択し、ファイルを指定します（または .mcpb を拡張機能ウィンドウにドラッグします）。
3. フォームに入力します — DBHawk Base URL、API Token（任意。マスク表示され、OS のキーチェーンに保存されます。ブラウザーからサインインする場合は空のままにします）、Default Datasource（任意）— 入力後、保存します。
4. トークンを設定していない場合、最初の DBHawk ツール呼び出し時にブラウザーで DBHawk のサインイン画面が開きます。サインインして許可をクリックします。Claude がサインイン待ちと報告した場合は、リクエストをもう一度実行してください。

Claude Desktop はファイルからインストールした拡張機能を自動更新しません。アップグレードするには、新しい .mcpb をダウンロードして再度インストールしてください。これは Claude Code プラグインとは別のものなので、マーケットプレイスのプラグインをインストールする必要はありません。

Claude Desktop（手動設定、上級者向け）

.mcpb を使わず手動で接続する場合は、バンドルを絶対パスで指定します。claude_desktop_config.json を編集します （Windows：%APPDATA%\Claude\claude_desktop_config.json、 macOS：~/Library/Application Support/Claude/claude_desktop_config.json）。

{
  "mcpServers": {
    "dbhawk": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\...\\dbhawk-mcp-plugin\\dbhawk\\mcp-server\\dist\\dbhawk-mcp.mjs"],
      "env": {
        "DBHAWK_BASE_URL": "https://demo.dbhawk.example.com",
        "DBHAWK_TOKEN": "PASTE_MCP_TOKEN_HERE",
        "DBHAWK_DEFAULT_DATASOURCE": ""
      }
    }
  }
}

トレイアイコンを含め、Claude Desktop を完全に再起動してください。

---

設定

サーバーには3つの値が必要です（トークンの所有者には ACCESS_TO_DATA が必要です）。

設定	必須	意味
ベース URL（DBHAWK_BASE_URL）	はい	DBHawk のベース URL。例：https://demo.dbhawk.example.com（末尾に /api を付けないでください）
API トークン（DBHAWK_TOKEN）	いいえ	空の場合：初回利用時にブラウザーからサインインします（DBHawk 7.0.1 以降）。それ以外の場合：MCP スコープの個人トークン（dbh_…）。DBHawk → User Profile → API Token から取得します。実行時に JWT と交換されます。個人トークンをそのまま貼り付けてください。JWT は貼り付けないでください
デフォルトのデータソース（DBHAWK_DEFAULT_DATASOURCE）	いいえ	ツール呼び出しで datasource が省略された場合に使用するデータソース

Claude Code — ガイド付きセットアップダイアログ（推奨）

このプラグインでは、dbhawk/.claude-plugin/plugin.json の userConfig フィールドとしてこれらの値を宣言しているため、プラグインを有効にすると Claude Code が入力を求めます。トークンフィールドは sensitive に設定されているため、入力時にマスクされ、安全なストレージ（OS のキーチェーン／~/.claude/.credentials.json）に保存されます。settings.json や git に保存されることはありません。dbhawk/.mcp.json では ${user_config.dbhawk_token} などを使って値を設定します。

後から再入力または変更するには、プラグインを再度有効にするか、対話なしで設定します。

claude plugin install dbhawk@dbhawk-marketplace \
  --config dbhawk_base_url=https://demo.dbhawk.example.com \
  --config dbhawk_token=dbh_... \
  --config dbhawk_default_datasource=

Claude Desktop — 環境変数

Desktop はプラグインや userConfig を認識しません。上記の claude_desktop_config.json ブロック内で、3つの値を env として渡してください。

---

ツール

ツール	DBHawk エンドポイント
list_datasources	GET /datasources
get_datasource	GET /datasources/{ds}
list_catalogs	GET /datasources/{ds}/catalogs（MSSQL／Snowflake 用。カタログ階層がない DB では空になります）
list_schemas	GET /datasources/{ds}/schemas
list_objects	GET /datasources/{ds}/schemas/{schema}/objects
list_columns	GET /datasources/{ds}/schemas/{schema}/objects/{object}/columns
get_permissions	GET /permissions（ユーザーの MCP ティア、許可された操作、行数上限、確認要件）
run_query	POST /datasources/{ds}/query。readOnly: true を指定します（読み取りのみ。ティアで書き込みが許可されていても読み取りのみ。行数上限は 200／5000）
explain_plan	POST /datasources/{ds}/explain（1つの接続上で実行計画を作成して読み取ります。ステートメントは実行されません。ティアに explain_plan が必要です）
list_sessions	GET /datasources/{ds}/sessions（アクティブなデータベースセッション。active_sessions が必要です）
kill_session	POST /datasources/{ds}/sessions/{id}/kill（一覧にあるセッションを1つ終了します。破壊的操作で、confirm フローが必要です。kill_session が必要です）
execute_statement	POST /datasources/{ds}/query（データ／スキーマの変更。MCP ティアで許可されている場合のみ実行できます。confirm フローが必要です）
text_to_sql	POST /datasources/{ds}/ai/ask
optimize_sql	POST /datasources/{ds}/ai/optimize
format_sql	POST /format-query

読み取り、書き込み、MCP ティア

ユーザーが実行できる操作は、DBHawk でユーザーグループごとにMCP ティア（Admin → MCP Management → MCP Tiers）として設定します。 デフォルトのティアは読み取り専用です。上位のティアでは EXPLAIN、DML（INSERT／UPDATE／DELETE／MERGE）、DDL、管理操作が追加されます。get_permissions は、モデルにそのティアで許可されている操作を伝えます。

意図的に、読み取りと書き込みは別々のツールになっています。run_query は読み取り専用（readOnlyHint）として注釈されており、ティアで書き込みが許可されていても、DBHawk はこのツール経由の書き込みを拒否します。execute_statement は破壊的操作（destructiveHint）として注釈されているため、Claude などの MCP クライアントは呼び出しごとにユーザーに確認を求めます。この設定を維持し、「常に許可」にはしないでください。ティアでも確認が必要な場合、DBHawk は最初の呼び出しに { confirmationRequired: true, executed: false } と応答し、confirm: true を付けて再度呼び出した場合にのみステートメントを実行します。読み取り専用のデータソースでは、ティアの設定にかかわらず書き込みは拒否されます。

プロンプトの例：「利用できるデータソースはどれですか？」 → 「Postgres-Demo の public スキーマにあるテーブルを表示して」 → 「customers にはどのような列がありますか？」 → 「先月の注文数をステータス別に教えて」（テキストから SQL を生成 → 実行）。

---

メンテナー向け — 公開と再ビルド

マーケットプレイスを公開する

cd dbhawk-mcp-plugin
git init && git add . && git commit -m "DBHawk MCP plugin"
git remote add origin [email protected]:datasparc/dbhawk-mcp-plugin.git
git push -u origin main

その後、ユーザーは上記の 2 つの /plugin コマンドを実行します。Anthropic が厳選する claude-plugins-official ディレクトリに掲載するには、プラグインディレクトリの申請フォームから申請してください（別途審査があります）。ご自身のマーケットプレイスは、それを行わなくてもすぐに利用できます。

バンドルを再ビルドする（index.js の編集後）

cd dbhawk/mcp-server
npm install        # once, pulls the SDK + esbuild (build-time only)
npm run build      # regenerates dist/dbhawk-mcp.mjs
git add dist/dbhawk-mcp.mjs && git commit -m "rebuild bundle"

dist/dbhawk-mcp.mjs は意図的にコミットしています。これはユーザーが実行する成果物です。node_modules/ はコミットしません。

テスト

cd dbhawk/mcp-server
npm test           # builds the bundle, then runs test/*.test.js
npm run test:only  # runs the tests against the current bundle, without rebuilding

テストでは、実際のバンドルを stdio 経由で起動し、公式 MCP クライアントで操作して、すべてのリクエストを記録する DBHawk の偽 HTTP サーバー（test/helpers.js）に接続するため、DBHawk インスタンスは必要ありません。ツールカタログとアノテーション、読み取り／書き込みの契約（run_query は常に readOnly: true を送信し、execute_statement は要求された場合のみ confirm を送信）、ツールからエンドポイントへのマッピング、トークン交換（ヘッダー、JWT キャッシュ、401 時の再交換 1 回）、およびエラー報告をテストします。CI（.github/workflows/mcp-server.yml）では Node 18/20/22 でテストを実行し、コミット済みの dist/ バンドルが古い場合、mcpb/server のコピーが一致しない場合、またはマニフェスト、server.json、index.js のバージョンが一致しない場合にも失敗します。

デスクトップ拡張機能（.mcpb）をビルドしてリリースする

mcpb/ フォルダーは拡張機能のソースです。Desktop の設定フォームに表示される user_config フィールドを宣言する mcpb/manifest.json と、同じ dist/ バンドルのコピーである mcpb/server/dbhawk-mcp.mjs が含まれます。バンドルを再ビルドした後、コピーを更新し、パッケージ化してリリースします。

cp dbhawk/mcp-server/dist/dbhawk-mcp.mjs mcpb/server/dbhawk-mcp.mjs   # keep the copy in sync
npx @anthropic-ai/mcpb validate mcpb/manifest.json                   # optional sanity check
npx @anthropic-ai/mcpb pack mcpb dbhawk-<version>.mcpb                # produces the .mcpb

# SBOM of everything inlined into the bundle (all deps are devDependencies, so don't --omit dev)
(cd dbhawk/mcp-server && npm sbom --sbom-format cyclonedx) > dbhawk-mcp-<version>.cdx.json

gh release create v<version> dbhawk-<version>.mcpb dbhawk-mcp-<version>.cdx.json \
  --title "DBHawk <version>" --notes "DBHawk MCP desktop extension"

.cdx.json は CycloneDX SBOM で、dist/dbhawk-mcp.mjs にインライン化された esbuild の正確なパッケージバージョンを列挙しています。そのため、バンドルを展開せずに監査できます。.mcpb と同様に Git の追跡対象外で、リリースアセットとしてのみ配布されます。

リリースごとに mcpb/manifest.json の version を更新してください（Desktop はこれに基づいてアップグレードを判定します）。.mcpb は Git の追跡対象外 です。ツリーには含めず、リリースアセットとして配布します。プラグインと拡張機能のバージョンを揃えるため、mcpb/manifest.json のバージョンを dbhawk/.claude-plugin/plugin.json と一致させてください。

---

トラブルシューティング

• token exchange failed: 401/403 — 個人用のDBHAWK_TOKENが誤っている、失効している、または有効期限切れです。ユーザーがMCPアクセスグループに所属していない場合や、（SSO/SAMLユーザーの場合）サインインの再検証期間が過ぎている場合もあります。IDプロバイダー経由でDBHawkに一度ログインすると、同じトークンを再び使用できます。必要に応じて再発行してください。
• DBHawk API 401/403（交換後）— スコープが誤っているか、ユーザーにACCESS_TO_DATA権限がありません。
• … needs MCP operation(s) …, which your MCP tier … does not allow — ステートメントの種類がユーザーのMCPティアで許可されていません（デフォルトのティアは読み取り専用です）。管理者がユーザーのグループのいずれかに、より高いティアを割り当てます（DBHawk → Admin → MCP Management → MCP Tiersを開き、User GroupダイアログでMCP Tierを設定します）。
• … cannot run as a read-only query. Use the execute_statement tool instead. — 書き込みがrun_query経由で送信されました。モデルはexecute_statementを使用する必要があり、その際にクライアントがユーザーに確認を求めます。
• Datasource '…' is read-only …（403）— データソースがDBHawkで読み取り専用に設定されているため、MCPティアで許可されていても書き込みは拒否されます。読み取りは引き続き可能です。
• confirmationRequired: true, executed: false — エラーではありません。ティアによって書き込みの確認が求められています。ステートメントをユーザーに表示し、承認後にconfirm: trueを指定してexecute_statementを再度呼び出してください。
• Sign in to DBHawk in the browser window that just opened … — トークンが設定されておらず、ブラウザーでのサインインがまだ完了していません。サインインしてAllowをクリックし、その後リクエストを再実行してください（ウィンドウが表示されない場合は、メッセージにURLが記載されています）。別のユーザーとしてサインインするには、上記のdbhawk-mcpフォルダーにあるoauth-*.jsonファイルを削除してください。
• This DBHawk server does not support signing in from the extension — DBHawkサーバーがMCPコネクターより古いバージョンです。個人用トークンを設定してください。
• Missing configuration（起動時）— DBHAWK_BASE_URLが設定されていません。
• Invalid configuration（起動時）— DBHAWK_BASE_URLがhttps://／http://のURLではない、認証情報やクエリ、末尾の/apiが含まれている、またはDBHAWK_TOKENが個人用のdbh_…トークンではなくJWTです。
• /mcpにサーバーが表示されない — Node ≥ 18であること、およびインストール済みプラグインにdist/dbhawk-mcp.mjsが存在することを確認してください。Claude Desktopではnodeのフルパスを使用してください（DesktopのPATHは最小限です）。