# SQLite MCP Server (複数DBエイリアス登録版)

SQLiteデータベースをMCP (Model Context Protocol) 経由で操作できるサーバーです。
起動時に複数のDBを「エイリアス=パス」の形で登録しておき、ツール呼び出し時にはエイリアス名で
DBを選択します。実行時に任意のファイルパスを受け付けないため安全です。

## 機能(ツール)

- `list_databases` — 登録されているDBのエイリアス一覧を表示
- `list_tables` — 指定DB内の全テーブル名を一覧表示
- `describe_table` — 指定テーブルのスキーマ(カラム/型/外部キー/インデックス)を取得
- `read_query` — SELECT / WITH / PRAGMA を実行(読み取り専用)
- `write_query` — INSERT / UPDATE / DELETE / DDL を実行(データ変更)

`list_tables`/`describe_table`/`read_query`/`write_query` は任意の `database` 引数(エイリアス名)を
受け付けます。登録DBが1つだけの場合は省略可能(自動的にそれがデフォルトになります)。
2つ以上登録している場合は毎回 `database` の指定が必須です。

## セットアップ

```bash
npm install
```

## 起動(動作確認・デバッグ用)

以下は**手動でサーバー単体を起動して動作確認する場合**のコマンドです。
Claude DesktopやClaude Codeから使う場合は、この節のコマンドを毎回手動で叩く必要はありません
(下記「MCPクライアントへの登録」で設定しておけば、各クライアントがこのコマンドを自動的に実行します)。

`エイリアス=パス` の形式で、1つ以上のDBを指定して起動します。

```bash
node index.js main=/path/to/main.db logs=/path/to/logs.db
```

1つだけ登録する場合(この場合は `database` 引数を省略できます):

```bash
node index.js main=/path/to/main.db
```

## 環境変数

| 変数名 | 説明 |
|---|---|
| `SQLITE_READONLY=1` | すべての接続を読み取り専用で開く(`write_query` は使用不可になる) |

## 使用例

```jsonc
// 登録済みDB一覧を確認
{ "tool": "list_databases", "arguments": {} }

// "main" DBのテーブル一覧
{ "tool": "list_tables", "arguments": { "database": "main" } }

// "logs" DBに対してクエリ
{ "tool": "read_query", "arguments": { "sql": "SELECT * FROM events", "database": "logs" } }

// DBが1つしか登録されていない場合は database 省略可
{ "tool": "read_query", "arguments": { "sql": "SELECT * FROM users" } }
```

## MCPクライアントへの登録

ここで登録するのは「起動コマンドの情報」であり、サーバー自体を起動するわけではありません。
登録しておくと、Claude DesktopやClaude Codeがセッション開始時に、登録された `command`/`args` を
使って自動的に `node index.js ...` を裏側で実行してくれます。手動で起動する必要はなくなります。

### Claude Desktop

**設定ファイルの場所:**

| OS | パス |
|---|---|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

このファイルに以下を追加します(パスは環境に合わせて絶対パスで指定):

```json
{
  "mcpServers": {
    "sqlite": {
      "command": "node",
      "args": [
        "/絶対パス/sqlite-mcp-server/index.js",
        "main=/絶対パス/main.db",
        "logs=/絶対パス/logs.db"
      ]
    }
  }
}
```

設定後、Claude Desktopを再起動すると `sqlite` サーバーのツールが利用可能になります。

### Claude Code(CLI / VS Code拡張)

VS Code内のターミナル、または通常のターミナルから `claude` コマンドで登録するのが基本です。
コマンドを実行すると、内容が設定ファイルに書き込まれます(下記参照)。

```bash
claude mcp add --transport stdio sqlite -- node /絶対パス/sqlite-mcp-server/index.js main=/絶対パス/main.db logs=/絶対パス/logs.db
```

- `--` の後ろがそのままサーバー起動コマンドとして渡されます。
- 読み取り専用にしたい場合は `--env SQLITE_READONLY=1` を追加します:
  ```bash
  claude mcp add --transport stdio --env SQLITE_READONLY=1 sqlite -- node /絶対パス/index.js main=/絶対パス/main.db
  ```
- デフォルトはローカルスコープ(自分の現在のプロジェクトのみ)。全プロジェクトで使うには `--scope user`、チームで`.mcp.json`として共有するには `--scope project` を付けます。
  ```bash
  claude mcp add --transport stdio --scope user sqlite -- node /絶対パス/index.js main=/絶対パス/main.db
  ```

登録内容の確認・削除:

```bash
claude mcp list
claude mcp remove sqlite
```

**設定ファイルを直接手動編集したい場合**、スコープによって書き込み先が異なります:

| スコープ | 設定ファイルの場所 | 用途 |
|---|---|---|
| `user`(全プロジェクト共通) | `~/.claude.json` | 自分の全プロジェクトで使う |
| `project`(チーム共有・git管理) | プロジェクトルートの `.mcp.json` | チームで共有、gitにコミットする想定 |
| `local`(デフォルト・自分のみ) | `~/.claude.json` 内のプロジェクトごとの設定(自分専用、非公開) | 自分だけ・このプロジェクトのみ |

DBのエイリアスを追加・変更したい場合、これらのファイルの該当サーバーの `args` 配列に
`"エイリアス=/絶対パス/db.db"` の形式で1項目追加すれば反映されます(JSON構文に注意)。
`.mcp.json`(projectスコープ)の場合は次のような形になります:

```json
{
  "mcpServers": {
    "sqlite": {
      "command": "node",
      "args": [
        "/絶対パス/sqlite-mcp-server/index.js",
        "main=/絶対パス/main.db",
        "logs=/絶対パス/logs.db",
        "reports=/絶対パス/reports.db"
      ]
    }
  }
}
```

編集後は `claude` セッションを再起動すると反映されます。

VS CodeでClaude Codeパネルを開く(または`claude`セッションを開始する)と、`list_databases`や`read_query`などのツールが利用可能になります。

## 注意事項

- `write_query` はSQLインジェクション対策として `?` プレースホルダの利用を推奨します(`params` 引数)。
- テーブル名は英数字とアンダースコアのみを許可するようにバリデーションしています。
- エイリアス名は英数字・アンダースコア・ハイフンのみ使用できます。
- 各DBへの接続は初回アクセス時に開かれ、以降は使い回されます。サーバー終了時にすべてクローズされます。
- 起動時に登録したエイリアス以外のDBには一切アクセスできません(任意パスの受け付けなし)。
- 本番データベースに接続する場合は `SQLITE_READONLY=1` での起動を検討してください。