mcp-devdb

ローカル開発用データベースのための安全な読み取り専用 MCP サーバー。コーディングエージェントは開発用 DB を常に参照する必要があります。スキーマ、サンプルデータ、クエリプラン、テーブルサイズなどです。しかし、素朴なデータベースコネクタではフル書き込みアクセスを許してしまいます。mcp-devdb は、堅牢な読み取り専用 SQL ガード、カラムマスキング、結果上限、セッションごとのクエリ予算の背後でイントロスペクションツールを公開する Model Context Protocol サーバーという、保護された代替手段です。

v1 のバックエンド: PostgreSQL (postgres 経由) と SQLite (better-sqlite3 経由)。アダプタインターフェースはエンジンに依存しないため、MySQL も後から追加できます。

クイックスタート

1. サーバーが実行される場所の隣に mcp-devdb.json を作成します (mcp-devdb.example.json を参照):

{
  "databases": {
    "app": { "url": "postgres://dev:dev@localhost:5432/app_development" },
    "cache": { "url": "sqlite:./data/cache.db" }
  }
}

2. 実行します:

npx mcp-devdb --config ./mcp-devdb.json

サーバーは stdio 経由で MCP を話します。MCP クライアントをそのコマンドに向けてください。接続文字列は設定ファイルまたは環境変数にのみ存在します ("url": "env:MY_DB_URL"、または設定ファイルなしの MCP_DEVDB_URL フォールバック)。モデルが接続文字列を提供することはできません。

Claude Code

claude mcp add devdb -- npx mcp-devdb --config /absolute/path/to/mcp-devdb.json

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "devdb": {
      "command": "npx",
      "args": ["mcp-devdb", "--config", "/absolute/path/to/mcp-devdb.json"]
    }
  }
}

Related MCP server: MCP PostgreSQL

ツール

database は、データベースが 1 つだけ設定されている場合は省略可能です。複数ある場合は、使用するものを指定します。

設定

カレントディレクトリの mcp-devdb.json、または --config による任意のパス:

{
  "databases": {
    "app": {
      "url": "postgres://dev:dev@localhost:5432/app_development",
      "allowTables": ["users", "orders", "public.events_*"],
      "denyTables": ["audit_log"]
    },
    "billing": { "url": "env:BILLING_DEV_DATABASE_URL" }
  },
  "maskPatterns": ["password", "secret", "token", "key", "hash", "ssn", "card"],
  "queryBudget": 100,
  "rowLimit": 200,
  "byteLimit": 262144,
  "statementTimeoutMs": 5000
}

• allowTables / denyTables — 大文字と小文字を区別しない名前で、* ワイルドカードを使用可能。ドットを含むルールは schema.table に一致。deny が優先。空でない許可リストは排他的。

• maskPatterns — カラム名に一致させる大文字と小文字を区別しない正規表現。

• CLI フラグ: --config <path>、--no-mask (カラムマスキングを無効化)、--help、--version。

セキュリティモデル (概要)

完全な脅威モデルは SECURITY.md にあります。要約:

• 読み取り専用ガード: すべての run_query/explain_query ステートメントはトークン化され (引用符、E'...' エスケープ、コメント、ドル引用符文字列)、SELECT / WITH / EXPLAIN / SHOW / VALUES で始まる必要があります。複数ステートメントの入力と、トップレベルでの書き込み/DDL キーワードは拒否されます。CTE の後の INSERT は検出され、SELECT 'DROP TABLE x' は誤検知ではありません。

• エンジンレベルの強制: SQLite ファイルは読み取り専用で開かれます。PostgreSQL セッションは default_transaction_read_only=on、明示的な BEGIN READ ONLY トランザクション、ステートメントタイムアウトで実行されます。

• カラムマスキングはデフォルトでオン (無効にするには --no-mask)、結果上限、セッションごとのクエリ予算 (デフォルト 100。使い切るとサーバーの再起動を促します)。

• 認証情報がモデルに渡ることはありません: 接続文字列はローカルの設定/環境変数からのみ取得され、すべてのエラーメッセージから削除されます。

スモークテスト

scripts/verify-stdio.mjs は一時 SQLite データベースを構築し、node dist/cli.js を起動して、生の JSON-RPC で stdio 経由の実際の MCP ハンドシェイクを駆動します。実際の出力:

$ node scripts/verify-stdio.mjs
initialize -> mcp-devdb 0.1.0 (protocol 2025-06-18)
tools/list -> db_overview, describe_table, explain_query, list_tables, run_query, sample_rows
tools/call list_tables ->
{
  "database": "demo",
  "dialect": "sqlite",
  "tableCount": 2,
  "tables": [
    {
      "schema": null,
      "name": "orders",
      "type": "table",
      "rowEstimate": 3,
      "sizeBytes": 4096,
      "sizePretty": "4.0 KiB"
    },
    {
      "schema": null,
      "name": "users",
      "type": "table",
      "rowEstimate": 2,
      "sizeBytes": 4096,
      "sizePretty": "4.0 KiB"
    }
  ]
}
tools/call run_query "DROP TABLE users" -> isError=true
  Query rejected by read-only guard: Only read-only statements are allowed; the statement must start with one of: SELECT, WITH, EXPLAIN, SHOW, VALUES
SMOKE TEST PASSED

制限事項

• MySQL はまだありません。 src/adapters/types.ts の DbAdapter インターフェースが拡張ポイントです。

• 開発用データベースのみ。 ガードは SQL レベルの書き込みをブロックしますが、SELECT でも副作用のある不適切にラベル付けされた関数や拡張関数を呼び出す可能性があります (例: 独自の読み取り専用でない接続を開く dblink)。開発用データベースでは許容されますが、本番環境には絶対にポイントしないでください。SECURITY.md を参照してください。

• ガードは保守的です。禁止キーワードと同じ名前の引用符なしカラム (例: 文字通り update という名前のカラム) は拒否されます。続行するには引用符 ("update") で囲んでください。

• SELECT ... FOR UPDATE は拒否されます (行ロックを取得するため)。

• SQLite の行数は COUNT(*) を使用します。巨大なファイルでは list_tables が遅くなる可能性があります。

開発

npm install
npm run lint && npm run typecheck && npm test && npm run build
node scripts/verify-stdio.mjs

ライセンス

MIT — Copyright (c) 2026 Aminyx