Database MCP

@cocaxcode/database-mcp

データベースを、会話ひとつで。
33 個のツール · PostgreSQL · MySQL · SQLite · 接続グループ · ロールバック · ダンプ／復元 · スキーマの自動検出

概要 · 話しかけるだけ · 接続グループ · インストール · 機能 · ツールリファレンス · ストレージ · アーキテクチャ

クイック概要

データベース向けの最も充実した MCP サーバーです。3 種類のエンジン（PostgreSQL、MySQL、SQLite）にわたる 33 個のツールを備え、接続グループ、名前付き接続の管理、自動ロールバック、ダンプ／復元、MCP リソースを介したスキーマの自動検出、完全なクエリ履歴をすべて自然言語で利用できます。

単なるクエリ実行ツールではありません。データベースをフルに扱えるワークベンチです。接続をプロジェクトディレクトリに対応するグループに整理し、セッション間で保持される既定値を設定し、3 段階の詳細度でスキーマを調査し、書き込みのたびに変更前のスナップショットを取得し、逆 SQL で操作ミスを取り消し、データベース全体をダンプして復元し、実行したすべてのクエリをプロジェクトごと、接続ごとに記録できます。

すべての接続はグループに属します。グループにはスコープ（ディレクトリ）、既定の接続、アクティブな接続があります。スコープに含まれるディレクトリ内で作業すると、そのグループの接続だけが表示されます。余計な表示も混乱もありません。

必要なことを伝えるだけです。AI がスキーマを読み取り、SQL を作成して安全に実行します。LIMIT の自動挿入、変更前のスナップショット、破壊的操作の前の確認を備えています。クラウドアカウントも、ORM も、設定ファイルも不要です。認証情報がマシンの外に出ることはありません。すべてローカルで動作します。

Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Codex CLI、Gemini CLI、および MCP 互換クライアントで動作します。

話しかけるだけ

ツール名や SQL 構文を覚える必要はありません。したいことを伝えるだけです。

> "Connect to my local PostgreSQL on port 5432, database myapp, user admin"

> "Create a group called backend and add this directory"

> "Connect to my PostgreSQL on localhost, put it in the backend group"

> "Set local-pg as the default connection"

> "Show me all tables"

> "What columns does the users table have?"

> "Show me the last 10 orders with the customer name"
  -> AI reads FKs from schema, builds the JOIN, applies LIMIT 10

> "Insert a test user called Alice"
  -> Snapshot captured for rollback

> "Oops, undo that"
  -> Rows restored via reverse SQL

> "Switch to the production database for this session"
  -> Instant context change, all queries now go to prod

> "Delete all inactive users"
  -> "This will affect N rows. Call again with confirm=true to proceed."

> "What did I run today?"
  -> Full query history with timestamps and execution times

> "Dump the database — structure and data"
  -> SQL file generated, ready for restore

AI は MCP リソースを通じて、すでにスキーマを把握しています。テーブルを見つけるために db://schema を読み取り、カラム、外部キー、インデックスを確認するために db://tables/{name}/schema を読み取ります。複数のテーブルにまたがるデータを尋ねると、正しい JOIN を自動的に作成します。

接続グループ

すべての接続はグループに属します。グループはデータベース接続を整理する単位です。接続の範囲を限定し、整理された状態を保ち、自動化します。

グループには、次の3つの重要な概念があります。

• スコープ：グループの接続を共有するディレクトリです。スコープが設定されたディレクトリ内で作業すると、そのグループの接続だけが表示されます。グローバルな情報に煩わされることはありません。
• デフォルト：スコープが設定されたディレクトリに入ると自動的に有効になる接続です。セッションをまたいで保持されます。
• アクティブ：現在使用中の接続です。セッション内でのみ有効で、再起動するとデフォルトに戻ります。

実際のワークフローは次のとおりです。

"Create a group called backend"
"Add this directory as scope"
"Create a PostgreSQL connection called local-dev in the backend group"   <- auto-default (first connection)
"Create another called production in backend"
"List connections"                                                       <- shows local-dev (active, default)
"Switch to production"                                                   <- session only
"Set production as default"                                              <- persists between sessions

グループに最初に追加された接続が、自動的にデフォルトになります。接続を切り替えると、現在のセッションのアクティブ接続だけが変わります。再起動すると、デフォルトに戻ります。変更を維持したい場合は、新しいデフォルトを明示的に設定してください。

つまり、本番環境に切り替えてすばやくクエリを実行しても、次にプロジェクトを開いたときには開発用データベースに戻っているので安心です。

インストール

Claude Code

claude mcp add --scope user database -- npx -y @cocaxcode/database-mcp@latest

Claude Desktop

設定ファイルに追加します（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json、Windows の場合は %APPDATA%\Claude\claude_desktop_config.json）。

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

{
  "servers": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

codex mcp add database -- npx -y @cocaxcode/database-mcp@latest

[mcp_servers.database]
command = "npx"
args = ["-y", "@cocaxcode/database-mcp@latest"]

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

ドライバーのインストール

必要なドライバーだけをインストールしてください。ドライバーは実行時に動的に読み込まれます。

npm install -g postgres       # PostgreSQL (postgres.js)
npm install -g mysql2         # MySQL
npm install -g sql.js         # SQLite (runs in-process, no native bindings)

注記： npx を使用する場合、ドライバーはグローバルにインストールする必要があります。サーバーをグローバルにインストールした場合（npm install -g @cocaxcode/database-mcp）、ドライバーはローカルまたはグローバルにインストールできます。

機能

複数のデータベースを1つのインターフェースで

ほとんどのデータベース MCP サーバーでは、セッションごとに認証情報を再設定する必要があります。このサーバーではその必要はありません。名前付き接続はグループ内に保持されるため、一度作成すれば、いつでも使用できます。

名前付き接続は Git のブランチのように機能します。 グループ内に dev、staging、prod を一度作成すれば、常に利用できます。切り替えはすぐに完了します。コマンド1つで、再設定は不要です。

"Create a group called my-project and add this directory as scope"
"Create a connection called dev with host localhost, database myapp, user admin in my-project"
"Create a read-only connection called analytics pointing to ./data/metrics.db in my-project"
"Switch to dev"               -> queries go to PostgreSQL
"Switch to analytics"         -> queries go to SQLite
"Duplicate dev as dev-readonly with read-only mode"

グループごとにスコープが設定された接続により、プロジェクトごとに異なるデータベースが自動的に表示されます。プロジェクト A で作業中の場合は、プロジェクト A のグループと接続が表示されます。プロジェクト B のディレクトリに切り替えると、独自のデフォルトを持つプロジェクト B のグループが読み込まれます。手動での切り替えは不要で、プロジェクト間で干渉することもありません。

"Create a group called frontend with scope /home/user/frontend"
"Create a group called backend with scope /home/user/backend"

これで、各ディレクトリがそれぞれ独立した接続セットを持つようになります。

認証情報は100％ローカルに保存されます。 すべての接続は ~/.database-mcp/connections/ 内の JSON ファイルとして保存されます。パスワードがマシンの外に出ることはありません。クラウドに送信されることも、Git にコミットされることもありません。認証情報はお客様のものです。

実行中の管理。 会話の途中でも、接続の作成、複製、名前変更、テスト、エクスポート、切り替えができます。再起動も設定ファイルの編集も不要で、コンテキストが失われることもありません。

安全機能を標準搭載

ロールバック用スナップショット

変更操作のたびに変更前の状態をスナップショットとして保存します。どんな操作も元に戻せます。

"Show me available rollbacks"
"Rollback the last delete"
  -> "This will INSERT 47 rows back into orders. Confirm?"
  -> Rows restored via reverse SQL

スキーマのイントロスペクション

パターンによるフィルタリングに対応した、詳細度の異なる3つのレベルがあります。

"List all tables"                         -> names only (fast)
"Show me the users table with columns"    -> columns + types + nullable
"Full schema for orders including FKs"    -> columns + foreign keys + indexes
"Tables starting with user"              -> pattern: 'user%'

MCP リソース（db://schema および db://tables/{name}/schema）を使うと、AI エージェントがスキーマに自動でアクセスできます。複数テーブルへのクエリでも、SQL を手動で記述する必要はありません。

EXPLAIN によるクエリ実行

"Show me all users"
  -> SELECT * FROM users LIMIT 100         <- auto LIMIT

"Show the execution plan for this query"
  -> EXPLAIN ANALYZE with dialect-specific syntax (PostgreSQL/MySQL/SQLite)

圧縮モード（v0.3 以降）

SQL の結果には、1行あたり数キロバイトになる TEXT／JSON／HTML カラムが含まれることがよくあります。AI エージェントは、コンテキストウィンドウに届くすべてのバイト分のコストを負担します。execute_query、execute_mutation、explain_query では、行と構造を保ちながらトークンを60〜95％削減できる、4つの任意パラメーターを指定できます。

モード：

• minimal — rowCount、executionTimeMs、affectedRows、および最初の行のプレビューのみを返します。INSERT／UPDATE／DELETE の確認、COUNT クエリ、ポーリングに最適です。トークンを約90〜95％削減します。
• normal (デフォルト) — 全行を返しますが、各セルは max_cell_bytes で切り詰められ、…(+NB) マーカーが付きます。テーブル構造は保持されます。行の幅が広い場合、トークンを約60〜80％削減します。
• full — 結果全体を変更せずに返します。すべてのセルの完全な値が必要な場合に使用します。

SELECT * FROM blog_posts LIMIT 100 を実行した場合の一般的な削減量。content が1行あたり約2KBの HTML である場合（合計約200KB）：

実測値を用いた、未加工の psql との直接比較については、以下のネイティブの代替手段を参照してください。

完全な結果を取得する： 圧縮されたレスポンスには、必ず call_id が含まれます。後から完全なセルの値が必要になった場合は、inspect_last_query({ call_id }) を呼び出してください。SQL を再実行する必要はなく、データベースへの負荷や副作用を避けられます。結果は20スロットのリングバッファーに保持され、~/.database-mcp/last-queries/ に1時間の TTL で保存されます。

// Example: normal (default) response
{
  "call_id": "k3m9a2xp",
  "columns": ["id", "title", "content"],
  "rows": [
    { "id": 1, "title": "Hello", "content": "<h1>Long HTML…(+1847B)" }
  ],
  "rowCount": 1,
  "executionTimeMs": 12,
  "cells_truncated": 1,
  "hint": "1 cell(s) truncated to 500 bytes. Use inspect_last_query({ call_id: \"k3m9a2xp\" }) for full values.",
  "tokens_saved_estimate": 462
}

ネイティブの代替手段：実際のトークンコスト

database が利用できない場合に Claude Code が使えるネイティブの選択肢（Bash + psql、sqlite3、mysql CLI など）と、この MCP を比較します。

要約：生の psql と比較すると、execute_query はモードに応じてコンテキストトークンを 78%〜96% 削減でき、デバッグ情報も失われません。PostgreSQL テーブルの content 列に行ごとに約 1 KB の HTML が含まれる状況で、SELECT * FROM blog_posts LIMIT 5 を実行した実際の呼び出しを測定しました。

この表の数値が上記の「圧縮モード」セクションと異なる理由：ここでは実際の 5 行のクエリを測定している一方、前の表では内容量の多い 100 行の結果に換算しています。傾向と桁の大きさは同じです。

注意事項：

• 生の psql 出力は、行数が増えるほど扱いにくくなります。JSONB と長い TEXT 列にはネイティブのフィルターがありません。MCP のセル切り詰めでは、構造（行数と列一覧）を維持しながら、サイズの大きいセルを …(+NB) マーカーで省略します。
• inspect_last_query を使えば、SQL を再実行せずに完全な結果を取得できます。psql では再実行が必要となり、DB の CPU を再度消費するうえ、RETURNING 句で副作用を再び引き起こすリスクがあります。
• MCP には、ネイティブに直接相当する機能のないものもあります。プロジェクトディレクトリ単位の接続グループ、変更時の自動ロールバックスナップショット、クエリ履歴、MCP リソースによるスキーマのイントロスペクション、ダンプ／復元などです。
• 関連する場合、応答の末尾にスキーマコンテキストが追加されます（normal／full ではデフォルトで true）。エージェントがすでにスキーマを把握している場合は、include_schema_context: false で無効にできます。
• 登録された MCP ごとに、セッションあたり約 300〜600 トークンの固定オーバーヘッドが発生します（指示ブロックとツール名）。通常、損益分岐点はセッションあたりの実際のクエリ 1 件です。

ダンプと復元

SQL 形式でデータベース全体をバックアップします。構造のみ、または構造とデータの両方を対象にできます。

"Dump the database"
  -> Choose: structure only or full
  -> Choose: all tables or specific ones
  -> SQL file saved to .database-mcp/dumps/

"Restore from the last dump"
  -> Lists available dumps, asks for confirmation, executes

生成される SQL では、DROP TABLE IF EXISTS、外部キーの無効化／有効化、方言に対応した DDL が処理されます。

クエリ履歴

すべてのクエリがプロジェクトごとに、タイムスタンプ、接続、実行時間、結果タイプとともに記録されます。

"What queries did I run today?"
"Show me only mutations"
"History for the prod connection"

接続のエクスポートとインポート

"Export all connections"                    -> JSON with masked passwords
"Export with secrets included"             -> JSON with real credentials
"Import these connections: { ... }"        -> creates missing connections

ツールリファレンス

8 カテゴリに 33 個のツールと、2 つの MCP リソースがあります。

リソース： db://schema · db://tables/{tableName}/schema

ヒント： これらのツールを直接呼び出す必要はありません。やりたいことを説明するだけで、AI が適切なツールを選びます。

ストレージ

設計上、ストレージは2つの場所に分かれています。この分離には明確な意図があり、現実的な問題を解決します。認証情報はあなたのものであり、プロジェクトの履歴はプロジェクトのものです。

グローバル：~/.database-mcp/ — グループ、接続、認証情報、設定を保存します。ホームディレクトリ内に置かれます。プロジェクト内には置かれません。Git に含まれることもありません。明示的にエクスポートしない限り、誰とも共有されません。

プロジェクトごと：{project}/.database-mcp/ — クエリ履歴、ロールバック用スナップショット、データベースのダンプを保存します。プロジェクトディレクトリ内に置かれ、初回書き込み時に .gitignore に自動で追加されます。

~/.database-mcp/                          # Global (configurable via DATABASE_MCP_DIR)
├── groups/                               # Connection groups with scopes and defaults
├── connections/                          # Connection configs (credentials, chmod 600)
├── project-conns.json                    # Session-only active connections (cleared on restart)
└── config.json                           # Server config (limits)

{your-project}/.database-mcp/            # Per-project (auto-gitignored)
├── history.json                          # Query history (max 5000)
├── rollbacks.json                        # Pre-mutation snapshots (max 1000)
└── dumps/
    └── {conn}-{timestamp}-{mode}.sql     # Database dumps

その結果、プロジェクトのリポジトリを自由に共有できます。共同作業者は履歴とロールバック構造を利用できますが、認証情報は一切含まれません。各自がローカルで独自の接続とグループを作成します。

設定

会話から、または環境変数を使って設定できます。

"Set max rollbacks to 2000"
"Set max history to 10000"

優先順位：環境変数 > 保存済み設定 > デフォルト値。

警告： DATABASE_MCP_DIR を Git リポジトリ内のパスに上書きする場合は、認証情報がプッシュされないよう、.database-mcp/ を .gitignore に追加してください。

アーキテクチャ

src/
├── index.ts              # Entry point (StdioServerTransport)
├── server.ts             # createServer() factory
├── tools/                # 33 tool handlers (one file per category)
├── resources/            # MCP Resources (schema auto-discovery)
├── services/             # Business logic
│   ├── connection-manager    # Lazy connect, driver caching
│   ├── schema-introspector   # Multi-dialect introspection (3 detail levels)
│   ├── query-executor        # Read/mutation/explain with safety
│   ├── rollback-manager      # Snapshot capture + reverse SQL
│   ├── history-logger        # Per-project query log
│   └── dump-manager          # Dump/restore (SQL generation)
├── drivers/              # Database adapters (postgres, mysql, sqlite)
├── lib/                  # Types, storage, sanitization
└── utils/                # SQL classifier, parser, formatter

• @modelcontextprotocol/sdk と zod 以外のランタイム依存関係はゼロ
• 厳格な TypeScript — any は使用しません
• 動的なドライバー読み込み — 実行時に import('postgres') / import('mysql2/promise') / import('sql.js') を使用します
• tsup でバンドルすると 60KB 未満
• ファクトリーパターン — 分離されたテストインスタンス用の createServer(storageDir?, projectDir?)

MIT · cocaxcode 作成