mcp-sqlite-tools

mcp-sqlite-tools

安全なローカル SQLite データベース操作のための Model Context Protocol（MCP）サーバーです。MCP クライアントに、読み取り、書き込み、スキーマ、トランザクション、CSV、バックアップ、メンテナンスのための明示的なツールを提供します。

機能

• SQLite データベースを開く、作成する、調査する、バックアップする、VACUUM する、閉じる
• テーブルを一覧表示する、説明する、作成する、削除する
• 名前付きまたは位置指定のパラメーターを使って、ページ分割された読み取りクエリを実行する
• 明示的な書き込みクエリとスキーマクエリを実行する
• ヘッダー付き CSV ファイルをインポートおよびエクスポートする
• ネストされたセーブポイントを使ってトランザクションを実行する
• スキーマを SQL または JSON としてエクスポートおよびインポートする
• 設定によってデータベースと CSV のパスを制限する
• クライアントの承認ポリシー用に破壊的なツールを分類する
• ネイティブアドオンへの依存なしで、Node 組み込みの SQLite ドライバーを使用する

要件

• Node.js 24.12 以降
• stdio サーバーをサポートする MCP クライアント

MCP クライアントの設定

MCP クライアントは npx を使ってこのサーバーを起動するため、グローバルインストールは不要です。

MCPick でインストールする

MCPick を使うと、JSON を手動で編集せずに、対応クライアントへサーバーを追加できます。このコマンドは、デフォルトで Claude Code のローカルスコープを対象にします。

npx -y mcpick add \
  --name sqlite-tools \
  --command npx \
  --args "-y,mcp-sqlite-tools"

必要に応じて、クライアントとスコープを明示的に選択します。

npx -y mcpick add \
  --name sqlite-tools \
  --command npx \
  --args "-y,mcp-sqlite-tools" \
  --client vscode \
  --scope project

add コマンドは Claude Code、Gemini CLI、VS Code、Cursor、Windsurf、OpenCode、Pi に対応しています。npx mcpick clients を実行すると、現在のクライアント機能、スコープ、設定場所を確認できます。

例では、最新のパッケージリリースを参照しています。再現可能な設定にするには、--args 内の mcp-sqlite-tools を [email protected] のような正確なバージョンに置き換えてください。

手動設定

未対応のクライアントや高度な設定の場合は、サーバーを手動で追加してください。

{
	"mcpServers": {
		"mcp-sqlite-tools": {
			"command": "npx",
			"args": ["-y", "mcp-sqlite-tools"],
			"env": {
				"SQLITE_DEFAULT_PATH": ".",
				"SQLITE_ALLOW_ABSOLUTE_PATHS": "true",
				"SQLITE_BUSY_TIMEOUT": "30000",
				"SQLITE_JOURNAL_MODE": "wal",
				"SQLITE_BACKUP_PATH": "./backups"
			}
		}
	}
}

VS Code では mcpServers の代わりに servers オブジェクトを使用します。その他のクライアント向けの例については、設定ガイドを参照してください。

環境変数

変数	用途	デフォルト
SQLITE_DEFAULT_PATH	データベースファイルのベースディレクトリ	.
SQLITE_ALLOW_ABSOLUTE_PATHS	デフォルトディレクトリ外のパスを許可する	true
SQLITE_BACKUP_PATH	デフォルトのバックアップディレクトリ	デフォルトのデータベースパス
SQLITE_BUSY_TIMEOUT	SQLite のロック待機タイムアウト（ミリ秒）	30000
SQLITE_JOURNAL_MODE	delete、truncate、persist、または wal	wal
DEBUG	診断ログを有効にする	false

SQLITE_ALLOW_ABSOLUTE_PATHS=false の場合、相対パスと絶対パスは SQLITE_DEFAULT_PATH 内に解決される必要があります。シンボリックリンクを使ってこのディレクトリから抜けることはできません。

ファイル同期対象のディレクトリ内にあるデータベースでは、SQLITE_JOURNAL_MODE=delete を使用してください。安全でない SQLite モードの memory と off は受け付けられません。

SQLITE_MAX_QUERY_TIME は、非推奨のエイリアスとして引き続き利用できます。これは SQLITE_BUSY_TIMEOUT を指します。実時間でのクエリ実行時間を制限するものではありません。

ツール

MCP クライアントが明確な承認ルールを適用できるよう、ツールは目的別に分けられています。

安全で読み取り専用

ツール	目的
open_database	既存のデータベースを開きます
close_database	データベース接続を閉じます
list_databases	ディレクトリ内のデータベースファイルを検索します
database_info	ファイルと SQLite のメタデータを読み取ります
list_tables	テーブルとビューを一覧表示します
describe_table	列と制約を読み取ります
backup_database	一貫性のあるオンラインバックアップを作成します
export_csv	テーブルまたは読み取り専用クエリをエクスポートします
export_schema	スキーマを SQL または JSON としてエクスポートします
execute_read_query	SQLite の読み取り専用ステートメントを 1 つ実行します

書き込み、スキーマ、メンテナンス

ツール	目的
create_database	新しいデータベースファイルを作成します
create_table	検証済みの列からテーブルを作成します
drop_table	テーブルとそのデータを削除します
execute_write_query	INSERT、UPDATE、または DELETE を実行します
execute_schema_query	スキーマステートメントを 1 つ実行します
bulk_insert	レコードを一括で挿入します
import_csv	ヘッダー付きの CSV ファイルをインポートします
import_schema	SQL または JSON のスキーマオブジェクトを適用します
vacuum_database	データベースを再構築して空き領域を回収します
begin_transaction	トランザクションまたはネストされたセーブポイントを開始します
commit_transaction	トランザクションをコミットするか、セーブポイントを解放します
rollback_transaction	トランザクションまたはセーブポイントをロールバックします

パラメーター、レスポンス、使用例、ページネーション、CSV オプションについては、 完全な API リファレンス をご覧ください。

安全性モデル

サーバーは、すべての SQL 文字列を同じものとして扱うわけではありません。

• execute_read_query は SQLite のオーソライザー API を使用し、書き込み、 スキーマの変更、安全でない PRAGMA、アタッチ、複数のステートメントを拒否します。
• 書き込み、スキーマ、トランザクション、破壊的な管理操作には 個別のツールを使用するため、クライアントは承認を求めることができます。
• データベースと CSV のパスは、アクセス前に解決され、検証されます。
• ツールが生成する識別子は引用符で囲まれます。
• 値は SQL に直接埋め込むのではなく、パラメーターとしてバインドされます。
• バックアップには SQLite のオンラインバックアップ API を使用し、コミット済みの WAL データも含まれます。

クライアントでは、読み取り専用ツールを許可し、破壊的なツールには承認を必須にできます。 変更を承認する前に、必ず SQL とファイルパスを確認してください。スキーマの変更、インポート、 または大量の書き込みを行う前に、重要なデータベースをバックアップしてください。

なぜネイティブ SQLite なのか？

node:sqlite を使用すると、ネイティブアドオン、そのインストールスクリプト、プラットフォーム固有のバイナリが不要になります。本番環境へのクリーンインストールのサイズは、 better-sqlite3 を使用した場合の 31.3 MB から、ネイティブ SQLite では 3.6 MB へと減少し、88.5% 削減されました。npm の tarball 自体のサイズはほぼ同じです。ネイティブ版は 63.1 KB、 公開版は 60.0 KB です。大幅な削減は、インストールされる 依存関係ツリーで生じています。

この移行により、better-sqlite3 とその型パッケージも不要になります。 また、インストールが、ビルド済みアドオンの提供状況や、ネイティブコンパイラーが正常に動作するかどうかに左右されなくなります。

ドライバーベンチマーク

時間は短いほど優れています。これらの中央値は、20,000 行、ウォームアップ 2 回、各ドライバーでの測定 7 回に基づいています。各サンプルでは新しいデータベースを使用し、ドライバーの順序を交互にしています。挿入ワークロードを除き、セットアップは測定範囲外です。

ワークロード	node:sqlite	better-sqlite3	ネイティブの結果
挿入トランザクション	11.13 ms	23.78 ms	2.14×高速
インデックス付きポイント読み取り	25.23 ms	21.40 ms	17.9%低速
全行スキャン	6.39 ms	3.29 ms	94.3%低速
更新トランザクション	8.04 ms	15.40 ms	1.92×高速
オンラインバックアップ	0.55 ms	0.38 ms	45.0%低速

Linux x64、Node.js 24.15.0、AMD Ryzen AI 9 HX 370 で測定しました。Node は SQLite 3.51.3 を使用し、[email protected] は SQLite 3.53.3 を使用しました。これらのマイクロベンチマークが示すのはドライバー間のトレードオフであり、MCP のパフォーマンス全体ではありません。MCP のトランスポートと検証にかかるコストは含まれていません。

開発

git clone https://github.com/spences10/mcp-sqlite-tools.git
cd mcp-sqlite-tools
pnpm install
pnpm run check
pnpm test
pnpm run build

モジュールの役割やその他の開発コマンドについては、 開発とアーキテクチャ をご覧ください。

ドキュメント

• 設定
• API リファレンス
• 開発とアーキテクチャ

コントリビューション

Issue とプルリクエストを歓迎します。

ライセンス

MIT ライセンスです。LICENSE をご覧ください。