warehouse-mcp

warehouse-mcp

データウェアハウス向けの本番環境対応MCP（Model Context Protocol）サーバーです。読み取り専用の強制、5段階のロールベースアクセス制御、オプションのウェアハウスロール偽装（ネイティブRLS／CLS向け）、JSONL監査ログ、オプションの出力PIIマスキング、セッションごとに切り替え可能なオプションのセマンティックメタデータレイヤー（用語集＋テーブルドキュメント）を備えています。Dockerイメージをセルフホストするか、npx経由でインストールするか、今後提供予定のマネージドクラウド版をお待ちください。

ステータス： v0.4.x — v1の対象ウェアハウス一覧に対して本番環境で利用できる状態です。各リリースで追加された内容については、CHANGELOGをご覧ください。

デモ動画

CursorでのWarehouse MCPの動作

対応ウェアハウス

ウェアハウス	アダプターのドキュメント
Postgres 12+	docs/adapters/postgres.md
Oracle 12c+（Thinモード、Instant Client不要）	docs/adapters/oracle.md
Amazon Redshift（クラスター＋Serverless）	docs/adapters/redshift.md
Snowflake（鍵ペア認証）	docs/adapters/snowflake.md
Google BigQuery	docs/adapters/bigquery.md
DuckDB（ローカルファイルまたは:memory:）	docs/adapters/duckdb.md
MotherDuck（クラウドホスト型DuckDB、md:パス）	docs/adapters/duckdb.md

Databricks SQLは近日中に追加予定です。

提供するツール（16個、すべて読み取り専用）

ツール	目的
query	SELECTを実行します（バリデーターで読み取り専用を強制し、方言を考慮）
list_schemas、list_tables、describe_table	カタログを参照します
find_columns	LIKEパターンを使って、ウェアハウス全体から列名を検索します
get_foreign_keys	安全な結合に使える、宣言済みのFKリレーションシップを検出します
get_view_definition	ビューのSQL本体（ビジネスロジックが記述されている箇所）を読み取ります
sample_table、count_rows	データを確認し、スキャン前にサイズを調べます
column_stats、top_values	単一列のプロファイリングを行います
time_series	時間／日／週／月／四半期／年単位でグループ化します — すべての環境で方言に適合します
search_value	テーブルのテキスト列全体からリテラル値を検索します
glossary_lookup	セマンティックレイヤーのビジネス用語集の用語を読み取ります（メモリ内で処理し、ウェアハウスへのI/Oはありません）
schema_lookup	スキーマレベルのドキュメント（目的、所有者、更新、テーブル一覧）を読み取ります
table_lookup	1つのテーブルのセマンティックドキュメント全体（説明＋列メタデータ）を読み取ります

ロール（5 段階）

ロール	使用可能なツール
semantic_only	セマンティック検索ツール 3 種のみ — データウェアハウスには一切アクセスしません。ドキュメントビューアーのペルソナには semantic=on を組み合わせてください
metadata_only	カタログの探索とセマンティック検索 — 行データは読み取りません
reader_restricted	集計／サンプル／時系列 — 任意の SELECT は実行できません
reader	query と search_value を追加（一般的なアナリスト向けロール）
admin	すべての機能。ENABLE_WRITE_TOOLS のリリース後は書き込みツールも使用できます

キーごとのロールは MCP_API_KEYS=key:role[:set_role=warehouse_role][:semantic=on|off] で割り当てます。省略可能な set_role= ディレクティブは、Postgres／Redshift で SET ROLE を実行します。これにより、ウェアハウス独自の RLS／CLS／マスキングポリシーでキーごとのアクセスを適用でき、MCP 側でポリシーを重複して設定する必要がありません。省略可能な semantic=on|off ディレクティブは、そのキーに限り SEMANTIC_DEFAULT を上書きし、セッションで warehouse://semantic/* リソースを参照できるかどうかを制御します（docs/semantic-metadata.md を参照）。

複数の既存 DB ロール（finance、hr、payroll など）があり、多数のユーザーがいるデプロイメントについては、docs/multi-role-deployment.md をご覧ください。約 10 個の DB ロールを MCP キーにマッピングする方法、推奨される <area>／<area>_restricted パターン、静的キーから OIDC に移行するタイミングについて説明しています。

mcp 接続の設定例（ロールに応じて変更してください）：

{ "mcpServers": { "warehouse-admin-semanticon": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "http://localhost:3001/mcp", "--header", "Authorization: Bearer admin-key-change-me" ] }, "warehouse-admin-semanticoff": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "http://localhost:3001/mcp", "--header", "Authorization: Bearer admin-key-nosemantic" ] }, "warehouse-reader-semanticon": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "http://localhost:3001/mcp", "--header", "Authorization: Bearer reader-key-change-me" ] }, "warehouse-reader-semanticoff": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "http://localhost:3001/mcp", "--header", "Authorization: Bearer reader-key-nosemantic" ] }, "warehouse-reader-restricted-semanticon": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "http://localhost:3001/mcp", "--header", "Authorization: Bearer restricted-key-change-me" ] }, "warehouse-reader-restricted-semanticoff": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "http://localhost:3001/mcp", "--header", "Authorization: Bearer restricted-key-nosemantic" ] }, "warehouse-metadata-only-semanticon": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "http://localhost:3001/mcp", "--header", "Authorization: Bearer metadata-only-key-change-me" ] }, "warehouse-metadata-only-semanticoff": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "http://localhost:3001/mcp", "--header", "Authorization: Bearer metadata-only-key-nosemantic" ] }, "warehouse-docs-viewer-only": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "http://localhost:3001/mcp", "--header", "Authorization: Bearer docs_viewer_key_change_me" ] } } }

クイックスタート

オプション A — Docker compose（Postgres にデータを投入した 5 分間のデモ）

git clone https://github.com/kalehdoo/warehouse-mcp.git
cd warehouse-mcp
docker compose up
# server on http://localhost:3001, seeded ecommerce data in Postgres

オプション B — Docker で独自のウェアハウスに接続

同じイメージにすべてのアダプターが含まれています。WAREHOUSE_TYPE と、それに対応する認証情報を指定して選択してください。認証情報には、インラインの -e フラグではなく --env-file（またはシークレットマネージャー）を使うことをおすすめします。パスワードがシェルの履歴に残るのを防げます。

# Postgres (REDSHIFT_* env vars for Redshift; same driver under the hood)
docker run -d -p 3001:3001 \
  -e WAREHOUSE_TYPE=postgres \
  -e PG_HOST=db -e PG_DATABASE=analytics -e PG_USER=mcp_reader -e PG_PASSWORD=... \
  -e MCP_API_KEYS="$(openssl rand -hex 24):reader" \
  ghcr.io/kalehdoo/warehouse-mcp:latest

# Oracle (Thin mode, no Instant Client)
docker run -d -p 3001:3001 \
  -e WAREHOUSE_TYPE=oracle \
  -e ORACLE_USER=MCP_READER -e ORACLE_PASSWORD=... \
  -e ORACLE_CONNECT_STRING="db.host:1521/SERVICE" \
  ghcr.io/kalehdoo/warehouse-mcp:latest

# Snowflake (key-pair, mount the .p8)
docker run -d -p 3001:3001 \
  -e WAREHOUSE_TYPE=snowflake \
  -e SNOWFLAKE_ACCOUNT=xy12345.us-east-1 -e SNOWFLAKE_USER=MCP_READER \
  -e SNOWFLAKE_PRIVATE_KEY_PATH=/keys/snowflake.p8 \
  -e SNOWFLAKE_WAREHOUSE=COMPUTE_WH -e SNOWFLAKE_DATABASE=ANALYTICS \
  -v /opt/keys:/keys:ro \
  ghcr.io/kalehdoo/warehouse-mcp:latest

# BigQuery (mount the service-account JSON)
docker run -d -p 3001:3001 \
  -e WAREHOUSE_TYPE=bigquery \
  -e GOOGLE_APPLICATION_CREDENTIALS=/keys/bq-sa.json \
  -e BIGQUERY_PROJECT=my-gcp-project \
  -v /opt/keys:/keys:ro \
  ghcr.io/kalehdoo/warehouse-mcp:latest

# DuckDB (file or in-memory)
docker run -d -p 3001:3001 \
  -e WAREHOUSE_TYPE=duckdb -e DUCKDB_PATH=:memory: \
  ghcr.io/kalehdoo/warehouse-mcp:latest

# MotherDuck (hosted DuckDB)
docker run -d -p 3001:3001 \
  -e WAREHOUSE_TYPE=duckdb -e DUCKDB_PATH=md:my_database \
  -e MOTHERDUCK_TOKEN=... \
  ghcr.io/kalehdoo/warehouse-mcp:latest

オプション C — npx（コンテナー不要）

npx warehouse-mcp@latest init     # interactive setup; writes .env, prints Claude Desktop snippet
npx warehouse-mcp doctor          # verify the connection without booting the server
npx warehouse-mcp start           # bind the MCP server to MCP_SERVER_PORT (default 3001)

次に、AI クライアントから接続します。設定例：

• Claude Desktop
• Cursor
• Docker（本番環境）
• Kubernetes

「ウェアハウスがある」状態から「Claude がウェアハウスにクエリを実行している」状態までの手順を追ったガイドについては、オンボーディングガイドをご覧ください。よくあるエラーについては、トラブルシューティングをご覧ください。

ローカル開発

nvm use            # Node 20
npm install
npm test           # unit tests, sub-second
npm run lint
cp .env.example .env

実際の Postgres に対する testcontainers の統合テストを実行するには、npm run test:integration を実行してください（Docker が必要です）。

env の設定

1. MCP_API_KEYS
2. WAREHOUSE_TYPE
3. SEMANTIC_DIR

オプション：セマンティックメタデータ（v0.4 以降）

ウェアハウスに何があるかだけでなく、ウェアハウスが何を意味するのかを AI エージェントに教えます。ビジネス用語集とテーブルのセマンティクスを記述した YAML ファイルをディレクトリに配置し、SEMANTIC_DIR にそのパスを指定すると、エージェントは同じインメモリーインデックスに対する 2 つのアクセス経路を利用できます。

• warehouse://semantic/* の MCP リソース — クエリを発行する前に、ツール対応クライアント（Cursor、MCP Inspector）が先行して読み取ります。
• glossary_lookup、schema_lookup、table_lookup の MCP ツール — ツール中心の UI を持ち、リソースのみのサーバーを非表示にする場合があるクライアント（Claude Desktop）向けに、同じデータをツール経由で利用できます。インメモリーの Map.get のみで、ウェアハウスへの I/O はなく、監査コストも通常のツールログ 1 行分を超えません。

形式は、拡張部分（モデルごとの meta.schema:）を除き、dbt の schema.yml v2 に準拠しています。dbt を利用しているお客様は、既存の models/ ディレクトリを SEMANTIC_DIR に指定して、現在のファイルの大部分を再利用できます。docs/semantic-metadata.md およびスターター用の docs/semantic-templates/をご覧ください。

セッションごとの切り替え

セッションからセマンティックレイヤーが見えるかどうかは、YAML が読み込まれるかどうかとは別に制御されます。読み込みは SEMANTIC_DIR で制御し、セッションごとの表示は SEMANTIC_DEFAULT=on|off とキーごとの semantic=on|off オプション（または include_semantic JWT クレーム）で制御します。YAML は起動時に常に読み込まれて検証されるため、再起動せずにキルスイッチを切り替えられます。優先度の高い順に、3 つの優先レイヤーがあります。

1. JWT ごとのクレーム — include_semantic: true|false（OIDC）。
2. API キーごとのオプション — MCP_API_KEYS 内の semantic=on|off。
3. サーバーのデフォルト — SEMANTIC_DEFAULT=on|off（デフォルトは on）。

各ツール呼び出しの監査行には、解決済みの include_semantic 値が記録されるため、後からクエリの品質とセマンティック情報の公開状況を関連付けられます。

オプション：OpenTelemetry トレーシング

デフォルトでは無効です。環境変数に OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318/v1/traces を設定すると、サーバーがツール呼び出しごとのスパンを出力します。リソース属性：service.name=warehouse-mcp、service.version=<package.json version>。スパン属性：warehouse.tenant、warehouse.role。あらゆる OTLP/HTTP バックエンド（Grafana Tempo、Honeycomb、Datadog APM、New Relic、SigNoz）で動作します。

オプション：出力の PII マスキング

デフォルトでは無効です。GUARDRAIL_PII_MASK=on を設定すると、サーバーは結果の各行に含まれるメールアドレス、SSN、形式化された電話番号、IPv4 アドレス、および Luhn アルゴリズムで検証されたクレジットカード番号をマスキングします。マスキングのレベルは呼び出し元のロールによって異なります。admin にはそのまま表示され、reader には一部が表示され（a***@example.com）、reader_restricted には完全なマスキングタグが表示されます。

仕組み

リクエストの流れについては、アーキテクチャのドキュメントをご覧ください。MCP クライアントが呼び出しを行った際にどのファイルが実行されるのか、ガードレールのパイプラインがツールハンドラーの周囲でどのように構成されるのか、新しいツール／ガードレール／アダプターを追加する手順を説明しています。運用担当者、セキュリティレビュー担当者、コントリビューター向けの、1 ページで全体像を把握できる資料です。

セキュリティ

デプロイする前に、脅威モデルをご覧ください。OWASP Top 10 との対応、コードベースで軽減している脅威、デプロイ環境に委ねられている対策（TLS、シークレット管理、ネットワーク分離、コストのガードレール）を説明しています。脆弱性はSECURITY.mdに従って報告してください。

コントリビューション

Issue や PR を歓迎します。まずはCONTRIBUTING.mdをご覧ください。開発ワークフロー、アダプターの仕様、新しいデータウェアハウスの追加方法を説明しています。参加することで、行動規範に同意したものとみなされます。

ライセンス

Apache-2.0