db-mcp (SQLite MCP Server)

db-mcp（SQLite MCP Server）

SQLite MCP Server は、170 以上の特化型ツール、11 個のデータリソースと 11 個のヘルプリソース、10 個のプロンプト、DDL バックアップスナップショット付きの監査ログ、HTTP/SSE トランスポート、OAuth 2.1 認証、ツールのフィルタリング、きめ細かなアクセス制御、カテゴリ別で実行可能な対応を示す構造化エラー処理を備えています。WASM 版と better-sqlite3 版を利用できます。

Wiki • 変更履歴

---

🎯 当プロジェクトの特長

機能	説明
181+ の特化型ツール	利用可能な SQLite MCP サーバーの中で最も包括的です。コア CRUD、JSON/JSONB、FTS5 全文検索、統計分析、ベクトル検索、地理空間／SpatiaLite、イントロスペクション、マイグレーション、管理機能を備えています
詳細なオブザーバビリティ	Prometheus /metrics エクスポート、リアルタイムの sqlite://metrics MCP リソース、SystemDb サイドカーへの履歴データの永続化、コンプライアンスと調査のための詳細な sqlite_audit_search ツールを内蔵しています
動的な設定	優先順位ルールを備えた YAML／JSON 設定ファイルの完全サポート（--config）に加え、サーバーを再起動せずに実行時の設定（ログレベルなど）を更新できる sqlite_server_config ツールを備えています
高度なクエリと検索	O(1) のカーソルベースのキセットページネーション、ファセット検索の集計、さらに FTS5 とベクトル類似度を単一のツール呼び出しで連携させる Reciprocal Rank Fusion（RRF）を用いた sqlite_hybrid_search を備えています
AI によるインデックス推奨	sqlite_index_audit は EXPLAIN QUERY PLAN の結果を自動で分析し、ワークロードのパターンに基づいて最適化された複合インデックスと部分インデックスを提案します
リアルタイムサブスクリプション	ネイティブの resources/subscribe をサポートし、sqlite://schema の DDL 変更に応じたイベント駆動型通知と、定期的な sqlite://health の更新をクライアントに直接プッシュします
22 のリソース	11 個のデータリソース（schema、tables、table_schema、indexes、views、health、meta、audit、metrics、compile_options、pragma）と、11 個のヘルプリソース（sqlite://help ＋ グループごとのリファレンス）を備え、--tool-filter で絞り込めます
AI 対応プロンプト 10 個	スキーマの調査、クエリの作成、データ分析、最適化、マイグレーション、デバッグ、FTS5 とベクトル検索のハイブリッド検索のためのガイド付きワークフローを提供します
コードモード	トークンを大幅に節約： プロセスレベルの分離と厳格なタイムアウトを備えた V8 分離サンドボックス 内で、複雑な複数ステップの操作を実行できます。ツール呼び出しの往復に数千トークンを費やす代わりに、コードモードでは 180 以上の機能すべてをローカルで利用でき、トークンのオーバーヘッドを 70～90% 削減し、AI エージェントの推論能力を大幅に高めます
トークン最適化されたペイロード	すべてのツール応答はトークン使用量を最小限に抑えるよう設計されており、各応答に _meta.tokenEstimate が含まれるため、エージェントはトークンコストを把握できます。該当するツールには compact、nodesOnly、maxOutliers、minSeverity、maxInvalid パラメーターがあり、データへのアクセスを保ったまま応答サイズを制御できます
2 種類の SQLite バックエンド	コンパイル不要で移植性に優れた WASM（sql.js）と、トランザクション、ウィンドウ関数、SpatiaLite GIS などの全機能を備えた高性能な同時実行向け Native（better-sqlite3）を利用できます
OAuth 2.1 ＋アクセス制御	RFC 9728／8414 に準拠し、細かなスコープ（full、read、write、admin、db:*、table:*:*）と Keycloak 連携に対応した、エンタープライズ向けのセキュリティを備えています
スマートなツールフィルタリング	10 個のツールグループと 7 個のショートカットにより、IDE の制限内に収めながら、必要な機能だけを公開できます
HTTP ストリーミングトランスポート	最新のクライアント向けの Streamable HTTP（/mcp）と、後方互換性のための従来の SSE（/sse）を提供します。両方のプロトコルを同時にサポートし、セキュリティヘッダー、レート制限、ヘルスチェック、サーバーレス向けのステートレスモードを備えています
本番環境対応のセキュリティ	SQL インジェクション対策（パラメーター化クエリ＋Unicode 正規化を用いた WHERE 句の検証）、サンドボックス化されたコード実行（V8 の codeGeneration 制限、プロトタイプの凍結、29 個のブロックパターン、Proxy の無効化、RPC 許可リスト）、デフォルトで全拒否の CORS、フェイルクローズのスコープ適用、JWT クレームのサニタイズ、7 個のセキュリティヘッダー、ボディサイズ制限、Retry-After 付きのレート制限、スローロリス対策のタイムアウト、trustedProxyIps、オプトイン方式の HSTS、非 root の Docker、ビルドの来歴情報を備えています
保存時の暗号化	--encryption-key または DB_ENCRYPTION_KEY によるネイティブの SQLCipher をサポートしています。better-sqlite3-multiple-ciphers を動的に読み込み、機密クエリの漏えいを防ぐため、サイドカーの SystemDb 監査ログを自動的に暗号化します
厳格な TypeScript	厳格モードで any 型を使わない、100% 型安全なコードベースです。ユニットテスト 1911 件、E2E テスト 1136 件を備え、カバレッジは 90% です
決定論的なエラー処理	すべてのツールは、構造化された {success, error, code, category, suggestion, recoverable} 応答を返します。未加工の例外も、エラーの握りつぶしもありません。エージェントには、解読しにくい SQLite コードの代わりに、実行可能な提案を含む詳細なエラーコンテキストが提供されます
MCP 2025-03-26 準拠	ツールの安全性ヒント（sensitiveHint、readOnlyHint）、リソースの優先度、進捗通知を含むプロトコル全体をサポートしています

🚀 クイックスタート

オプション 1：Docker（推奨）

すぐにプルして実行します：

docker pull writenotenow/db-mcp:latest

ボリュームをマウントして実行します：

docker run -i --rm \
  -v $(pwd):/workspace \
  writenotenow/db-mcp:latest \
  --sqlite-native /workspace/database.db

オプション 2：Node.js のインストール

リポジトリをクローンします：

git clone https://github.com/neverinfamous/db-mcp.git

ディレクトリに移動します：

cd db-mcp

依存関係をインストールします：

pnpm install

プロジェクトをビルドします：

pnpm run build

ネイティブバックエンド（better-sqlite3 — 全機能を利用可能、Node.js のネイティブビルドが必要）でサーバーを実行します：

node dist/cli.js --transport stdio --sqlite-native ./database.db

または、WASM バックエンド（sql.js — クロスプラットフォーム対応、コンパイル不要）で実行します：

node dist/cli.js --transport stdio --sqlite ./database.db

バックエンドの選択： 全機能（181 MCP ツール／170 グループツール、トランザクション、ウィンドウ関数、SpatiaLite）を利用するには --sqlite-native を使用します。WASM モード（154 MCP ツール／143 グループツール、ネイティブ依存関係なし）には --sqlite を使用します。

動作確認

node dist/cli.js --transport stdio --sqlite-native :memory:

想定される出力：

[db-mcp] Starting MCP server...
[db-mcp] Registered adapter: Native SQLite Adapter (better-sqlite3) (sqlite:default)
[db-mcp] Server started successfully

テストスイートを実行します：

pnpm run test

前提条件

• ✅ Docker がインストールされ、実行中であること（Docker を使用する場合）
• ✅ Node.js 24+（LTS）（ローカルにインストールする場合）

コードモード：最大限の効率

コードモード（sqlite_execute_code）はトークン使用量を大幅に削減（70～90%）し、すべてのプリセットにデフォルトで含まれています。

コードはワーカースレッドのサンドボックスで実行されます。これは、独自のメモリ空間を持つ別個の V8 分離環境です。すべての sqlite.* API 呼び出しは、MessagePort ベースの RPC ブリッジを介してメインスレッドに転送され、実際のデータベース操作が実行されます。これにより、次の機能が提供されます。

• プロセスレベルの分離 — ユーザーコードは、ヒープ制限が適用された別個の V8 インスタンスで実行されます
• 読み取り専用の適用 — readonly: true の場合、無効化されたメソッドは Proxy トラップを介して、利用可能なメソッドを列挙した明確なエラーメッセージを返します
• 厳格なタイムアウト — 実行が設定した制限を超えると、ワーカーを終了します
• V8 コード生成の制限 — codeGeneration: { strings: false, wasm: false } により、V8 エンジンレベルで文字列からの eval() と Function() の構築を無効にします
• RPC の許可リスト — ホスト側で検証し、ワーカーによる許可されていない API メソッドの呼び出しを防ぎます
• 完全な API アクセス — sqlite.* を介して 10 個すべてのツールグループを利用できます（例：sqlite.core.readQuery()、sqlite.json.extract()）

必要に応じて、CODEMODE_ISOLATION=vm と CODEMODE_ISOLATION_INSECURE=1 を設定すると、プロセス内の vm モジュールサンドボックスに切り替えられます。

⚡ コードモードのみ（トークンを最大限に節約）

独自のセットアップを管理している場合は、コードモードのみを有効にして実行できます。単一のツールから、sqlite.* API を通じて 180 以上のツールに相当する機能を利用できます。

{
  "mcpServers": {
    "db-mcp-sqlite": {
      "command": "node",
      "args": [
        "/path/to/db-mcp/dist/cli.js",
        "--transport",
        "stdio",
        "--sqlite-native",
        "/path/to/database.db",
        "--tool-filter",
        "codemode"
      ]
    }
  }
}

これにより、sqlite_execute_code と組み込みツールのみが公開されます。エージェントは型付きの sqlite.* SDK を使用して JavaScript を記述し、クエリの組み合わせ、10 個すべてのツールグループにまたがる操作の連鎖、必要なデータだけの返却を一度の実行で行います。これは、Cloudflare が自社 API 全体向けに開発した コードモードのパターンを踏襲しています。機能の数にかかわらず、トークンコストは一定です。

ヒント

トークンを最大限に節約： 個別のツール呼び出しよりもコードモードを優先するよう、AI エージェントに指示してください。

「db-mcp を使用する際は、トークン使用量を最小限に抑えるため、複数ステップにわたるデータベース操作には個別のツール呼び出しではなく sqlite_execute_code（コードモード）を優先してください。」

---

🎛️ ツールのフィルタリング

重要

Cursor などの AI 対応 IDE にはツール数の上限があります。 ネイティブバックエンドではツールが 180 個以上あるため、上限内に収めるにはツールのフィルタリングが必要です。ショートカットを使うか、必要なものだけを有効にするためにグループを指定してください。

クイックスタート：推奨設定

スターター（core + json + text）

個別のツール呼び出しを使う場合、starter では Core + JSON + Text を利用できます。

{
  "args": ["--tool-filter", "starter"]
}

カスタムグループ

必要なグループだけを正確に指定します。

{
  "args": ["--tool-filter", "core,json,stats"]
}

ショートカット（定義済みバンドル）

注： ネイティブ版には、WASM では利用できない FTS5（5）、ウィンドウ関数（6）、トランザクション（8）、SpatiaLite（7）が含まれます。

ショートカット	WASM	ネイティブ	+ 組み込み	含まれるもの
starter	65	70	+4	Core、JSON、Text
analytics	67	73	+4	Core、JSON、Stats
search	51	56	+4	Core、Text、Vector
spatial	40	47	+4	Core、Geo、Vector
dev-schema	41	41	+4	Core、Introspection、Migration
minimal	25	25	+4	Core のみ
full	143	170	+4	すべて有効

ツールグループ（10 種類）

注： すべてのグループに、組み込みツール 4 種（server_info、server_health、list_adapters、sqlite_execute_code）が追加されます。

グループ	WASM	ネイティブ	+ 組み込み	説明
core	25	25	+4	基本的な CRUD、スキーマ、テーブル
json	25	25	+4	JSON/JSONB 操作、分析
text	15	20	+4	テキスト処理 + FTS5 + 高度な検索
stats	17	23	+4	記述統計、推測統計、ウィンドウ関数
vector	11	11	+4	ベクトルストレージ、類似性検索
admin	30	31	+4	DB のメンテナンス、バックアップ、仮想テーブル
transactions	0	8	+4	コミット、ロールバック、セーブポイント（ネイティブ版のみ）
geo	4	11	+4	地理空間機能 + SpatiaLite（ネイティブ版のみ）
introspection	10	10	+4	スキーママッピング、FK グラフ、分析
migration	6	6	+4	スキーマ移行の追跡（オプトイン）

構文リファレンス

プレフィックス	対象	例	効果
(なし)	ショートカット	starter	ホワイトリストモード： このショートカットのみ有効にします
(なし)	グループ	core	ホワイトリストモード： このグループのみ有効にします
(なし)	ツール	read_query	ホワイトリストモード： このツールのみ有効にします
+	グループ	+vector	このグループのツールを現在のセットに追加します
-	グループ	-admin	このグループのツールを現在のセットから削除します
+	ツール	+fuzzy_search	特定のツールを 1 つ追加します
-	ツール	-drop_table	特定のツールを 1 つ削除します

カスタムツールの選択

個々のツール名を（+ プレフィックスなしで）列挙すると、完全なカスタムホワイトリストを作成できます。有効になるのは指定したツールのみです。

ツールを正確に 3 つ有効にする（ホワイトリストモード）：

--tool-filter "read_query,write_query,list_tables"

異なるグループのツールを組み合わせる：

--tool-filter "read_query,fuzzy_search,vector_search"

ショートカットまたはグループと組み合わせる：

--tool-filter "starter,+vector_search,+fuzzy_search"

これは、最小限かつ正確な機能セットを必要とするスクリプト化されたクライアントや自動化されたクライアントに便利です。

例：

--tool-filter "starter"
--tool-filter "core,json,text,stats"
--tool-filter "starter,+stats"
--tool-filter "starter,-vector"

従来の構文（引き続きサポート）： 負のフィルター（例：-vector,-geo）から始めると、すべてのツールを有効にしてから差し引く指定として扱われます。

--tool-filter "-stats,-vector,-geo,-backup,-monitoring,-transactions,-window"

🔌 SQLite 拡張機能

SQLite は、組み込み拡張機能（better-sqlite3 にコンパイルされるもの）と、ロード可能な拡張機能（別途バイナリが必要なもの）の両方をサポートしています。

組み込み拡張機能（そのまま使用可能）

拡張機能	用途	状態
FTS5	BM25 ランキングによる全文検索	✅ 常に読み込み済み
JSON1	JSON 関数（json_extract など）	✅ 常に読み込み済み
R-Tree	バウンディングボックスの空間インデックス	✅ 常に読み込み済み

読み込み可能な拡張機能（インストールが必要）

拡張機能	用途	ツール数	CLI フラグ
CSV	CSV 仮想テーブル	2	--csv
SpatiaLite	高度な GIS 機能	7	--spatialite

拡張機能のインストール

CSV 拡張機能：

コンパイル済みバイナリをダウンロードするか、ソースからコンパイルしてください：https://www.sqlite.org/csv.html

環境変数を設定します（Linux/macOS）：

export CSV_EXTENSION_PATH=/path/to/csv.so

Windows では .dll を使用します：

export CSV_EXTENSION_PATH=/path/to/csv.dll

または CLI フラグを使用します：

db-mcp --sqlite-native ./data.db --csv

SpatiaLite 拡張機能：

お使いのプラットフォーム用のライブラリをインストールします：

• Linux (apt)： sudo apt install libspatialite-dev
• macOS (Homebrew)： brew install libspatialite
• Windows： https://www.gaia-gis.it/gaia-sins/ からダウンロードします

環境変数を設定します：

export SPATIALITE_PATH=/path/to/mod_spatialite.so

または CLI フラグを使用します：

db-mcp --sqlite-native ./data.db --spatialite

注： 拡張機能のバイナリは、お使いのプラットフォームおよびアーキテクチャに適合している必要があります。サーバーは一般的なパスを自動的に検索します。カスタムの場所を指定する場合は、CSV_EXTENSION_PATH / SPATIALITE_PATH 環境変数を使用してください。

📁 リソース

データリソース（11）

MCP リソースを使用すると、データベースのメタデータに読み取り専用でアクセスできます：

リソース	URI	説明	最小構成
sqlite_schema	sqlite://schema	データベーススキーマ全体	minimal
sqlite_tables	sqlite://tables	すべてのテーブルの一覧	minimal
sqlite_table_schema	sqlite://table/{tableName}/schema	特定のテーブルのスキーマ	minimal
sqlite_indexes	sqlite://indexes	データベース内のすべてのインデックス	minimal
sqlite_views	sqlite://views	データベース内のすべてのビュー	core,admin
sqlite_health	sqlite://health	データベースの健全性と状態	(読み取り専用)
sqlite_meta	sqlite://meta	データベースのメタデータと PRAGMA	core,admin
sqlite_compile_options	sqlite://compile_options	SQLite のコンパイル時ビルドオプション	(読み取り専用)
sqlite_pragma	sqlite://pragma	実行時の PRAGMA 設定のスナップショット	(読み取り専用)
sqlite_audit	sqlite://audit	直近の監査ログとバックアップ統計	--audit-log
sqlite_metrics	sqlite://metrics	サーバー内部のメトリクス	(読み取り専用)

ヘルプリソース（1 + 最大10件）

--tool-filter によって絞り込まれる、オンデマンドのツールリファレンスドキュメント：

リソース	URI	説明	登録条件
sqlite_help	sqlite://help	注意点、WASM と Native の違い、Code Mode API	常時
sqlite_help_core	sqlite://help/core	コアの CRUD とテーブル操作のリファレンス	core グループが有効な場合
sqlite_help_json	sqlite://help/json	JSON/JSONB 操作のリファレンス	json グループが有効な場合
sqlite_help_text	sqlite://help/text	テキスト処理と FTS5 のリファレンス	text グループが有効な場合
sqlite_help_stats	sqlite://help/stats	統計分析とウィンドウ関数のリファレンス	stats グループが有効な場合
sqlite_help_vector	sqlite://help/vector	ベクトル／セマンティック検索のリファレンス	vector グループが有効な場合
sqlite_help_geo	sqlite://help/geo	地理空間と SpatiaLite のリファレンス	geo グループが有効な場合
sqlite_help_admin	sqlite://help/admin	管理、バックアップ、仮想テーブルのリファレンス	admin グループが有効な場合
sqlite_help_transactions	sqlite://help/transactions	トランザクション制御のリファレンス	transactions グループが有効な場合
sqlite_help_introspection	sqlite://help/introspection	スキーマのイントロスペクション、FK グラフ、診断のリファレンス	introspection グループが有効な場合
sqlite_help_migration	sqlite://help/migration	マイグレーションの追跡、適用、ロールバックのリファレンス	migration グループが有効な場合

効率化のヒント： ツールの設定にかかわらず、データリソースは常に読み取り可能です。「Min Config」列は、リソースが公開する内容に対して操作するツールを提供する最小構成を示します。ヘルプリソースはオンデマンドで提供され、エージェントは特定のツールグループを扱う場合にのみ読み込みます。

💬 プロンプト（10件）

MCP プロンプトは、AI によるデータベースワークフローを提供します。

プロンプト	説明
sqlite_explain_schema	データベースの構造とリレーションシップを説明する
sqlite_query_builder	一般的な操作向けの SQL クエリの作成を支援する
sqlite_data_analysis	データのパターンを分析し、洞察を提供する
sqlite_optimization	データベースを分析し、最適化を提案する
sqlite_migration	データベースのマイグレーションスクリプトの作成を支援する
sqlite_debug_query	動作しない SQL クエリをデバッグする
sqlite_documentation	データベーススキーマのドキュメントを生成する
sqlite_summarize_table	テーブルをインテリジェントに分析し、要約する
sqlite_hybrid_search_workflow	FTS5 とベクトル検索を組み合わせたワークフロー
sqlite_demo	MCP の機能をインタラクティブにデモする

🔧 設定

環境変数

変数	デフォルト	説明
MCP_HOST	127.0.0.1	バインドするホスト/IP（Docker では 0.0.0.0）（CLI: --server-host）
SQLITE_DATABASE	—	SQLite データベースのパス（CLI: --sqlite / --sqlite-native）
DB_ENCRYPTION_KEY	—	SQLCipher 暗号化キー（ネイティブのみ）（CLI: --encryption-key）
DB_MCP_TOOL_FILTER	—	ツールのフィルター文字列（CLI: --tool-filter）
METRICS_EXPORT	—	HTTP /metrics でメトリクスをエクスポート（例：prometheus）（CLI: --metrics-export）
OAUTH_ENABLED	false	OAuth 2.1 を有効化（CLI: --oauth-enabled）
OAUTH_ISSUER	—	認可サーバーの URL（CLI: --oauth-issuer）
OAUTH_AUDIENCE	—	想定されるトークンのオーディエンス（CLI: --oauth-audience）
OAUTH_JWKS_URI	—	JWKS URI。省略時は自動検出されます（CLI: --oauth-jwks-uri）
OAUTH_CLOCK_TOLERANCE	60	クロック許容誤差（秒）（CLI: --oauth-clock-tolerance）
MCP_ENABLE_HSTS	false	HSTS ヘッダーを有効化（CLI: --enable-hsts）
NO_AUTH_ENFORCEMENT	false	HTTP の認証強制を明示的に無効化（CLI: --no-auth-enforcement）
LOG_LEVEL	info	ログの詳細度：debug、info、warning、error
METADATA_CACHE_TTL_MS	5000	スキーマキャッシュの TTL（ミリ秒）。DDL 操作時に自動的に無効化されます
CODEMODE_ISOLATION	isolate	Code Mode のサンドボックス：isolate（isolated-vm ネイティブ）または worker
CODE_MODE_MAX_RESULT_SIZE	102400	Code Mode の結果ペイロードの最大サイズ（バイト。デフォルトは 100KB、上限は 50MB）
MCP_RATE_LIMIT_MAX	100	IP ごとの最大リクエスト数／分（HTTP トランスポート）
CSV_EXTENSION_PATH	—	CSV 拡張機能バイナリのカスタムパス（ネイティブのみ）
SPATIALITE_PATH	—	SpatiaLite 拡張機能バイナリのカスタムパス（ネイティブのみ）
ALLOWED_IO_ROOTS	—	IO 操作で許可する絶対パスの JSON 配列またはカンマ区切りリスト
MCP_AUTH_TOKEN	—	HTTP 認証用のシンプルなベアラートークン（CLI: --auth-token）
AUDIT_LOG	—	監査ログのファイルパス、または stderr（CLI: --audit-log）
AUDIT_REDACT	true	監査ログ項目からツールの引数を秘匿（無効化するには CLI: --audit-no-redact）
AUDIT_READS	false	読み取りスコープのツール呼び出しも記録（CLI: --audit-reads）
AUDIT_BACKUP	false	変更前の DDL スナップショットを有効化（CLI: --audit-backup）
AUDIT_BACKUP_DATA	false	スナップショットにサンプルデータ行を含める（CLI: --audit-backup-data）

ヒント： 開発時は METADATA_CACHE_TTL_MS を小さく（例：1000）、スキーマが安定している本番環境では大きく（例：60000 = 1 分）設定します。スキーマキャッシュは DDL 操作（CREATE/ALTER/DROP）時に自動的に無効化されます。

CLI リファレンス

db-mcp [options]

Transport:    --transport <stdio|http|sse>  --port <N>  --server-host <host>  --stateless
Auth:         --oauth-enabled --oauth-issuer <url> --oauth-audience <aud>
Database:     --sqlite <path>  |  --sqlite-native <path>  [--encryption-key <key>]
Extensions:   --csv  --spatialite                         (native only)
Security:     --allowed-io-roots <paths>
Audit:        --audit-log <path>  --audit-no-redact  --audit-reads  --audit-backup  --audit-backup-data
Server:       --name <name>  --version <ver>  --metrics-export <type>  --tool-filter <filter>

CLI フラグは環境変数より優先されます。詳細については node dist/cli.js --help を実行してください。

📚 MCP クライアントの設定

~/.cursor/mcp.json、Claude Desktop の設定、または同等の設定に追加します：

{
  "mcpServers": {
    "db-mcp-sqlite": {
      "command": "node",
      "args": [
        "C:/path/to/db-mcp/dist/cli.js",
        "--transport",
        "stdio",
        "--sqlite-native",
        "C:/path/to/your/database.db",
        "--tool-filter",
        "codemode"
      ]
    }
  }
}

ヒント

バックエンドの切り替え： 上記の設定では Native バックエンド（better-sqlite3、181 個の MCP ツール）を使用しています。WASM バックエンド（sql.js、154 個の MCP ツール、ネイティブ依存関係なし）を使用するには、args 配列内の --sqlite-native を --sqlite に変更します。機能の違いについては、DOCKER_README のバックエンドオプションの表を参照してください。

バリエーション（上記の args 配列を変更します）：

バリエーション	変更内容
WASM バックエンド	--sqlite-native を --sqlite に置き換えます
インメモリデータベース	データベースのパスを :memory: に置き換えます
スタータープリセット	個別のツール呼び出しには "codemode" を "starter" に置き換えます
CSV 拡張機能	"--tool-filter" の前に "--csv" を追加します（Native のみ）
SpatiaLite	"--spatialite" を追加し、env: { "SPATIALITE_PATH": "/path/to/mod_spatialite" } を設定します（Native のみ）
Linux/macOS	スラッシュ区切りの Unix パスを使用します（例：/path/to/db-mcp/dist/cli.js）
Docker	"command": "node" を "command": "docker" に置き換え、args を run -i --rm -v ./data:/app/data writenotenow/db-mcp:latest で囲みます

公開するツールをカスタマイズするには、ツールのフィルタリングを参照してください。

🌐 HTTP/SSE トランスポート（リモートアクセス）

リモートアクセス、ウェブベースのクライアント、または HTTP 互換の MCP ホストには、HTTP トランスポートを使用します：

node dist/cli.js \
  --transport http \
  --port 3000 \
  --sqlite-native ./database.db \
  --allowed-io-roots $(pwd)

Docker：

docker run --rm -p 3000:3000 \
  -v ./data:/app/data \
  writenotenow/db-mcp:latest \
  --transport http --port 3000 \
  --sqlite-native /app/data/database.db \
  --allowed-io-roots /app/data

このサーバーは 2 つの MCP トランスポートプロトコルを同時にサポートしているため、新旧両方のクライアントが接続できます：

Streamable HTTP（推奨）

最新のプロトコル（MCP 2025-03-26）— 単一のエンドポイント、セッションベース：

メソッド	エンドポイント	用途
POST	/mcp	JSON-RPC リクエスト（initialize、tools/list など）
GET	/mcp	サーバー通知用の SSE ストリーム
DELETE	/mcp	セッションの終了

セッションは Mcp-Session-Id ヘッダーで管理されます。

ステートレスモード

セッションが不要なサーバーレス／ステートレス環境でのデプロイ向け：

node dist/cli.js --transport http --port 3000 --stateless --sqlite-native ./database.db --allowed-io-roots $(pwd)

ステートレスモードでは、GET /mcp は 405、DELETE /mcp は 204 を返し、/sse と /messages は 404 を返します。各 POST /mcp で新しいトランスポートが作成されます。

レガシー SSE（後方互換性）

レガシープロトコル（MCP 2024-11-05）— Python の mcp.client.sse などのクライアント向け：

メソッド	エンドポイント	用途
GET	/sse	SSE ストリームを開き、/messages?sessionId=<id> エンドポイントを返します
POST	/messages?sessionId=<id>	セッションに JSON-RPC メッセージを送信します

ユーティリティエンドポイント

メソッド	エンドポイント	用途
GET	/health	ヘルスチェック（レート制限を回避し、監視用に常時利用可能）

🔐 認証

db-mcp は、厳格な OAuth 2.1 認証を使用して HTTP トランスポートを保護します。

OAuth 2.1（エンタープライズ）

本番環境のマルチテナントデプロイメントに対応した、RFC 9728／8414 準拠の完全な OAuth 2.1 です。

node dist/cli.js \
  --transport http \
  --port 3000 \
  --sqlite-native ./database.db \
  --allowed-io-roots $(pwd) \
  --oauth-enabled \
  --oauth-issuer http://localhost:8080/realms/db-mcp \
  --oauth-audience db-mcp-server

追加フラグ： --oauth-jwks-uri <url>（省略時は自動検出）、--oauth-clock-tolerance <seconds>（デフォルト：60）。

OAuth スコープ

アクセス制御は OAuth スコープを通じて管理されます。

スコープ	説明
full	すべての操作への制限のないアクセス
read	すべてのデータベースへの読み取り専用アクセス
write	すべてのデータベースへの読み書きアクセス
admin	完全な管理者アクセス

RFC 準拠

この実装は、以下に準拠しています。

• RFC 9728 — OAuth 2.1 保護リソースメタデータ
• RFC 8414 — OAuth 2.1 認可サーバーメタデータ
• RFC 7591 — OAuth 2.1 動的クライアント登録

サーバーは /.well-known/oauth-protected-resource でメタデータを公開します。

Keycloak ユーザー向けの注意： トークンに正しい aud クレームを含めるには、クライアントに Audience mapper（Client → Client scopes → dedicated scope → Add mapper → Audience）を追加してください。

メモ

ツールごとのスコープ適用： スコープはツールレベルで適用されます。各ツールグループは、必要なスコープ（read、write、または admin）に対応付けられます。不明なツールや対応付けられていないツールは、デフォルトで admin になります（フェイルクローズ）。OAuth が有効な場合、すべてのツール呼び出しで、実行前に呼び出し元トークンのスコープが確認されます。OAuth が設定されていない場合、スコープの確認は完全にスキップされます。

ヒント

監査 ID の統合： 監査ログ（--audit-log）とともに OAuth が有効な場合、書き込み／管理者ツールの監査エントリには、認証済みユーザー（claims.sub）と付与されたスコープが自動的に記録されます。これにより、すべての変更を特定の ID に結び付ける完全なフォレンジック記録が得られます。OAuth がない場合、これらのフィールドは null／[] です。

警告

認証なしの HTTP： OAuth を有効にせず --transport http を使用すると、すべてのクライアントが制限なく完全なアクセス権を持ちます。本番環境の HTTP デプロイメントでは、必ず認証を有効にしてください。詳細については、SECURITY.md を参照してください。

🔐 保存データの暗号化（ネイティブのみ）

db-mcp は、better-sqlite3-multiple-ciphers ドライバーを介した SQLCipher による透過的なデータベース暗号化をサポートしています。暗号化が有効な場合、サーバーは対象データベース（新規作成の場合）とサイドカーの SystemDb 監査ログの両方を自動的に暗号化し、スキーマ、クエリ、結果を保存時に保護します。

重要な WASM の制限事項： WASM バックエンド（sql.js）は暗号化をサポートしていません。WASM バックエンドに暗号化キーを指定した場合、対象データベースについてはエラーを発生させずに無視されます。ただし、Native バックエンドと WASM バックエンドの両方が同じ --audit-log ファイルを共有していると、競合が発生する可能性があります（Native バックエンドが共有監査ログを暗号化するため、WASM バックエンドが読み込み時にクラッシュします）。デュアルバックエンド構成でこれを避けるには、WASM インスタンスに別の監査ログ（例：--audit-log mcp-audit-wasm.db）を割り当ててください。

キーの設定： キーは --encryption-key CLI フラグまたは DB_ENCRYPTION_KEY 環境変数で指定できます。

1. 強力なパスフレーズ： 標準的な文字列です。SQLCipher は PBKDF2 キー導出を自動的に使用します。

   DB_ENCRYPTION_KEY="your-strong-passphrase-here"
   

2. 生の 16 進数キー（最高のパフォーマンス）： PBKDF2 キー導出のオーバーヘッドを省くには、x を先頭に付け、シングルクォートで囲んだ正確な 256 ビットの生の 16 進数キーを指定します。

   DB_ENCRYPTION_KEY="x'2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99'"
   

警告

監査ログとの互換性： DB_ENCRYPTION_KEY 環境変数はグローバルに適用され、内部の SystemDb が監査ログ（--audit-log）を復号しようとします。既存の監査ログが暗号化されていない場合、サーバーは file is not a database というエラーで起動に失敗します。対象データベースのみを暗号化し（監査ログは暗号化しない）たい場合は、グローバル環境変数ではなく --encryption-key CLI フラグを使用してください。

📊 ベンチマーク

パフォーマンスベンチマークでは、Vitest bench（tinybench）を使用して、重要なホットパスにおけるフレームワークのオーバーヘッドを測定します。このスイートでは、実際のデータベース I/O と比べて、フレームワークの処理による負荷が無視できるほど小さいことを検証します。

• ツールのディスパッチ: 6–14M ops/sec — Map ベースの検索によるコストは実質ゼロです
• 認証スコープのチェック: 4–8M ops/sec — OAuth ミドルウェアによる測定可能なレイテンシーはありません
• 識別子の検証: 4–7M ops/sec — SQL のサニタイズはほぼ瞬時です
• スキーマキャッシュのヒット: 3–6M ops/sec — メタデータの検索により、重複したクエリを回避します
• デバッグログ（フィルタリング済み）: 5–11M ops/sec — 無効化されたログレベルでは、実際に何も処理されません
• Code Mode のセキュリティ: 一般的なコードで約 0.2–1.3M 件の検証/秒、ブロック対象のパターンは 1–2 µs で拒否されます
• サンドボックスの実行: 約 0.5–4.9K 件の実行/秒 — 単純なコードは V8 isolate を介して 0.2–1.5 ms で往復します

pnpm run bench            # Run all benchmarks
pnpm run bench:verbose    # Verbose mode with detailed timings

ベンチマーク	測定内容
ハンドラーのディスパッチ	ツールの検索、エラーの生成、進捗通知のオーバーヘッド
ユーティリティ	識別子のサニタイズ、WHERE 句の検証、SQL の検証
ツールのフィルタリング	フィルターの解析、グループの検索、メタグループカタログの生成
スキーマの解析	単純・複雑・大容量ペイロードの Zod スキーマ検証と失敗時の処理
ロガーとサニタイズ	ログ呼び出しのオーバーヘッド、メッセージのサニタイズ、機密データのマスキング
トランスポートと認証	トークンの抽出、スコープのチェック、エラーの整形、レート制限
Code Mode	サンドボックスの作成、プールのライフサイクル、セキュリティ検証、実行
データベース操作	PRAGMA 操作、テーブルメタデータ、クエリ結果の処理、スキーマのキャッシュ
リソースとプロンプト	URI の照合、コンテンツの組み立て、プロンプトの生成、ツールのインデックス作成

---

コントリビューション

コントリビューションを歓迎します。プルリクエストを送信する前に、コントリビューションガイドラインをお読みください。

セキュリティ

セキュリティに関する懸念については、セキュリティポリシーをご覧ください。

⚠️ 認証情報は絶対にコミットしないでください - シークレットは .env（gitignore 対象）に保存してください

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

行動規範

このプロジェクトに参加する前に、行動規範をお読みください。