Easy Sqlite Mcp

easy-sqlite-mcp

Node.js と TypeScript で実装された Model Context Protocol (MCP) サーバーです。LLM が SQLite データベースと直接やり取りできるように設計されています。

このプロジェクトでは、Node.js、TypeScript、公式 MCP SDK、better-sqlite3 を使用しています。stdio 経由で動作するため、Claude Desktop、Codex、OpenCode などの MCP クライアントから直接利用できます。

特長

• 手動モードと固定起動モードに対応した SQLite 接続管理
• データ取得用の読み取り専用クエリツール
• データ変更およびスキーマ文用の実行ツール
• テーブル、ビュー、インデックス、トリガーを検出するスキーマ探索ツール
• better-sqlite3 による軽量で同期的な SQLite アクセス

このプロジェクトの better-sqlite3 には Node.js 22 以降が必要です。Windows でプリビルド済みバイナリを最も確実に利用するには、Node.js 22 LTS を使用してください。

必要条件

• Node.js 22 以降（Node.js 22 LTS を推奨）
• npm
• アクセス可能な SQLite データベースファイル

インストール

npx でサーバーを直接実行します。

npx -y easy-sqlite-mcp

リポジトリをクローンしてローカル開発を行う場合：

cd easy-sqlite-mcp
npm install
npm run build

設定

MCP クライアントの設定またはシェル環境で、環境変数を使ってサーバーを設定します。

変数	必須	デフォルト	説明
SQLITE_PATH	いいえ	-	SQLite データベースファイルへの絶対パスまたは相対パスです。設定すると、サーバーは固定モードで起動します

シェルでの設定例：

SQLITE_PATH=/absolute/path/to/database.sqlite npx -y easy-sqlite-mcp

PowerShell の場合：

$env:SQLITE_PATH = "C:\data\database.sqlite"
npx -y easy-sqlite-mcp

サーバーは stdio 経由で通信し、通常は手動で実行するのではなく、MCP クライアントによって起動されます。

ツールの使い方がわからない場合や、操作に失敗した場合は、まず sqlite_manual を呼び出してください。安全な使用ルール、プレースホルダーの説明、ライフサイクルに関する注意事項を含む組み込みマニュアルが返されます。

モード

Easy SQLite MCP は、2 種類の起動モードに対応しています。MCP クライアントとエージェントが有効なモードを明確に把握できるよう、サーバーの説明は起動時に生成されます。

手動モード

SQLITE_PATH が指定されていない場合は、手動モードが使用されます。

このモードでは、エージェントがデータベースを明示的に開閉する必要があります。

1. データベースツールを使用する前に、sqlite_open(path) を呼び出します。
2. クエリ、実行、スキーマ探索ツールを使用します。
3. 完了したら sqlite_close を呼び出します。

一度に開ける SQLite データベースファイルは 1 つだけです。別のファイルを開くと、先に現在の接続が閉じられます。

サーバーの説明：

Manual: This is a SQLite tool. Before using it, call sqlite_open(path) to open a database file. After use, call sqlite_close to close it. Only one database file can be open at a time.

手動モードで利用できるツール：

• sqlite_open
• sqlite_close
• sqlite_status
• sqlite_query
• sqlite_execute
• sqlite_list_tables
• sqlite_describe_table

固定モード

環境変数として SQLITE_PATH が指定されている場合は、固定モードが使用されます。

このモードでは、サーバーは起動時に設定済みの SQLite データベースを自動的に開きます。エージェントが sqlite_open を呼び出す必要はなく、接続の切り替えは無効になります。

サーバーの説明：

Fixed: This is a SQLite tool connected to Path:<SQLITE_PATH>

固定モードで利用できるツール：

• sqlite_status
• sqlite_query
• sqlite_execute
• sqlite_list_tables
• sqlite_describe_table

Claude Desktop の例

手動モード：

{
  "mcpServers": {
    "easy-sqlite-mcp": {
      "command": "npx",
      "args": ["-y", "easy-sqlite-mcp"]
    }
  }
}

固定モードの例：

{
  "mcpServers": {
    "easy-sqlite-mcp": {
      "command": "npx",
      "args": ["-y", "easy-sqlite-mcp"],
      "env": {
        "SQLITE_PATH": "/absolute/path/to/database.sqlite"
      }
    }
  }
}

設定を更新した後、Claude Desktop を再起動してください。

Codex config.toml の例

手動モード：

[mcp_servers.easy-sqlite-mcp]
args = ["-y", "easy-sqlite-mcp"]
command = "npx"
enabled = true

固定モードの例：

[mcp_servers.easy-sqlite-mcp]
args = ["-y", "easy-sqlite-mcp"]
command = "npx"
enabled = true

[mcp_servers.easy-sqlite-mcp.env]
SQLITE_PATH = "/absolute/path/to/database.sqlite"

OpenCode opencode.jsonc の例

手動モード：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "easy-sqlite-mcp": {
      "type": "local",
      "command": ["npx", "-y", "easy-sqlite-mcp"],
      "enabled": true
    }
  }
}

固定モードの例：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "easy-sqlite-mcp": {
      "type": "local",
      "command": ["npx", "-y", "easy-sqlite-mcp"],
      "enabled": true,
      "environment": {
        "SQLITE_PATH": "/absolute/path/to/database.sqlite"
      }
    }
  }
}

利用可能なツール

ツール	説明
sqlite_manual	組み込みマニュアルを返します。SQLite ツールの使い方がわからない場合や、操作エラーの診断が必要な場合は、まずこれを使用してください
sqlite_open	SQLite データベースファイルを開きます。手動モード専用
sqlite_close	現在のデータベース接続を閉じます。手動モード専用
sqlite_status	接続状態と現在のデータベースの概要を返します
sqlite_query	読み取り専用の SELECT クエリを実行します
sqlite_execute	書き込みまたは変更を行う SQL 文を実行します
sqlite_list_tables	データベース内のすべてのユーザーテーブルを一覧表示します
sqlite_describe_table	テーブルのスキーマを説明します

手動モードに関する注意事項

• クエリまたは実行ツールを呼び出す前に、sqlite_open(path) を使用してください。
• 作業が終わったら、sqlite_close を使用してください。
• 同時に開けるデータベースファイルは1つだけです。
• ライフサイクルやプレースホルダーに関するガイダンスが必要な場合は、sqlite_manual を使用してください。

開発

npm run build
npm run dev
npm test

ライセンス

MIT。詳細は LICENSE.md を参照してください。