DBeast PostgreSQL MCP

---

DBeast は、Model Context Protocol を通じて、Claude、Cursor、Windsurf、VS Code Copilot などの AI アシスタントを PostgreSQL に接続します。汎用的な execute_sql の抜け道をひとつ公開するのではなく、スキーマの検出、安全なクエリ実行、影響分析、パフォーマンスレビュー、セキュリティチェック、メンテナンスレポート、レプリケーション監視、データ品質の検査に対応する 21 個の専用ツールを提供します。

---

デモ

Claude が DBeast MCP ツールを使って PostgreSQL データベースを監査し、セキュリティとメンテナンスのリスクを特定し、破壊的な SQL を実行せずにクリーンアップの影響を確認する様子をご覧ください。

---

動作の仕組み

AI assistant  --MCP stdio-->  DBeast server  --asyncpg-->  PostgreSQL
Claude/Cursor                  Python local                 Local, RDS,
Windsurf/VS Code               subprocess                   Supabase, Neon

DBeast はローカルの stdio MCP サーバーとして動作します。IDE またはデスクトップアシスタントがサブプロセスとして起動し、環境変数を通じてデータベースの認証情報を渡します。アシスタントが DBeast のツールを呼び出し、DBeast が PostgreSQL にクエリを実行し、構造化された結果をアシスタントに返します。HTTP サービスや追加のインフラストラクチャは不要です。

---

クイックスタート

1. インストール

git clone https://github.com/snss10/DBeast.git
cd DBeast
pip install -e .

開発用の場合：

pip install -e ".[dev]"

任意：.env.example を .env にコピーし、データベースの認証情報を設定します。

2. 確認

dbeast

または、ソースのエントリーポイントを直接実行します。

python src/server.py

3. MCP クライアントを設定する

Cursor または Windsurf の最小構成：

{
  "mcpServers": {
    "dbeast": {
      "type": "stdio",
      "command": "python",
      "args": ["/absolute/path/to/DBeast/src/server.py"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}

一般的な設定ファイルの場所：

クライアント	設定ファイルの場所
Cursor	プロジェクトルートの .mcp.json、またはグローバル設定の ~/.cursor/.mcp.json
VS Code	.vscode/settings.json、またはキー mcp.servers を指定したユーザー設定
macOS の Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Windows の Claude Desktop	%APPDATA%\Claude\claude_desktop_config.json
Windsurf	.mcp.json

クライアントごとの設定例、Docker、RDS、Supabase、Neon、SSH トンネル、AWS Secrets Manager、トラブルシューティングについては、SETUP.md をご覧ください。

4. 簡単な質問や複雑な質問をする

接続すると、アシスタントは簡単な検索質問に答えるだけでなく、複数ステップのデータベース調査も実行できます。

簡単な例：

Show me the schema for the orders table.
Which queries are slowest right now?
Run a security audit on the public schema.
Generate a Mermaid ERD for the sales schema.

より複雑な例：

Before I archive old sessions, estimate how many rows would be affected, identify related tables, and tell me the rollback risk.
Investigate why the dashboard query is slow, explain the execution plan, and suggest safe indexes.
Review the public schema for maintenance issues, security risks, and data quality problems, then summarize the top priorities.
Compare table growth, dead tuples, and index health across all schemas and recommend what to vacuum or reindex first.

---

ツール

DBeast は 10 のカテゴリにわたる 21 個の MCP ツールを公開します。

接続

ツール	説明
connect	PostgreSQL に接続し、現在のステータスを確認するか、ローカルデータベースを検出します
disconnect	現在のデータベース接続を閉じます
health_check	接続状態、プールの健全性、PostgreSQL のバージョン、拡張機能を確認します

スキーマ検出

ツール	説明
get_schema	スキーマ、テーブル、列、インデックス、リレーションシップ、任意の Mermaid ERD を一覧表示します
dependency_analysis	データベースオブジェクトの名前変更、削除、変更の前に、オブジェクトの依存関係をマッピングします

データアクセス

ツール	説明
execute_query	行数上限を自動的に適用して、読み取り専用の SELECT クエリを実行します

クエリ分析

ツール	説明
analyze_query	クエリ構造、警告、最適化のヒントを解析して確認します
query_optimizer	指定したクエリに推奨されるインデックスと書き換えを提示します
analyze_impact	実行せずに、書き込みクエリの影響、リスクレベル、影響を受ける行、ロールバック時の情報をプレビューします

データベースの健全性

ツール	説明
database_health	キャッシュヒット率、接続数、トランザクションの経過時間、テーブルの健全性、全体的な健全性の指標を確認します
query_performance	PostgreSQL の統計情報から、低速または負荷の高いクエリを報告します

セキュリティ

ツール	説明
security_audit	ロール、権限、スーパーユーザーアカウント、公開スキーマへの公開状況を確認します
sensitive_data_scan	カラム名とスキーマパターンから、個人情報（PII）やシークレットと思われるデータを検出します

メンテナンス

ツール	説明
maintenance_analysis	バキュームの状態、デッドタプル、分析のタイムスタンプ、インデックスの健全性を確認します
partition_analysis	パーティションの健全性、行の分布、パーティション不足のリスクを確認します

データ品質

ツール	説明
data_quality_report	NULL 率、カーディナリティ、値の分布、外れ値を分析します
duplicate_detection	選択したキー列を対象に、重複行を検出します

サーバー設定

ツール	説明
configuration_review	PostgreSQL の設定とチューニングの機会を確認します
replication_status	レプリケーションの遅延、WAL 送信側／受信側の状態、レプリケーションスロットを確認します

監査

ツール	説明
get_audit_logs	指定した日付の MCP ツール呼び出しログを取得します
list_audit_files	利用可能な監査ログファイルを一覧表示します

---

推奨ワークフロー

まず、スキーマを確認します。

get_schema()
get_schema(schema='public')

安全な読み取りクエリを実行します。

execute_query(query='SELECT * FROM orders ORDER BY created_at DESC')

リスクのある書き込みをプレビューします。

analyze_impact(query='DELETE FROM sessions WHERE last_active < now() - interval ''30 days''')

健全性とメンテナンスを確認します。

database_health()
maintenance_analysis(schema='public')
query_performance()

ほとんどの分析ツールでは、schema パラメーターを指定できます。

maintenance_analysis(schema='public')  -> analyze one schema
maintenance_analysis(schema='all')     -> analyze every schema
get_schema(format='mermaid')           -> generate an ERD diagram

---

対応データベース

プロバイダー	接続方法
ローカル PostgreSQL	DATABASE_URL または個別の DB_* 変数
Docker PostgreSQL	明示的な変数、または connect(discover=true)
AWS RDS / Aurora	直接 URL、SSH トンネル、または AWS Secrets Manager
Supabase	Dashboard の設定にあるプーラー接続文字列
Neon	Console の接続詳細にある接続文字列
Railway / Render / Fly.io	プロバイダーの接続文字列
任意の PostgreSQL ホスト	標準 PostgreSQL URL

---

設定

接続方法を 1 つ選択してください。

# Full URL
DATABASE_URL=postgresql://user:pass@host:5432/db

# Or individual variables
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=secret
DB_NAME=mydb
DB_SSLMODE=prefer

# Or AWS Secrets Manager
AWS_SECRET_NAME=my-rds-secret
AWS_REGION=us-west-2

実行時に接続することもできます。

connect(url='postgresql://user:pass@host:5432/db')
connect(host='localhost', user='postgres', password='secret', database='mydb')
connect(aws_secret_name='my-secret', aws_region='us-west-2')

主な設定：

変数	デフォルト	説明
DBEAST_DEFAULT_ROW_LIMIT	100	execute_query が返す最大行数
DBEAST_QUERY_TIMEOUT	300	クエリ実行のタイムアウト（秒）
DBEAST_COMMAND_TIMEOUT	300	SQL コマンドのタイムアウト（秒）
DBEAST_SSL_VERIFY	true	証明書が localhost と一致しない SSH トンネルでは false に設定します
DBEAST_SCHEMA_CACHE_TTL	60	スキーマキャッシュの TTL（秒）。0 にするとキャッシュを無効にします
DBEAST_AUDIT_ENABLED	true	MCP ツール呼び出しを記録します
DBEAST_AUDIT_DIR	logs/mcp_audit	監査ログのディレクトリ

設定の全項目については、SETUP.md を参照してください。

---

安全性モデル

クエリの種類	DBeast の動作
SELECT	行数を自動的に制限して実行します
INSERT / UPDATE / DELETE	実行せず、影響をプレビューします
DROP / TRUNCATE	実行せず、影響を受けるオブジェクトとリスクを報告します

整形済みのレスポンスと JSON レスポンスでは、一貫したラッパーを使用します。

{
  "success": true,
  "data": { "...": "..." },
  "meta": {
    "connected": true,
    "source": "tool"
  }
}

---

監査ログ

DBeast は、説明責任の確保とデバッグのために MCP ツール呼び出しを記録します。

DBEAST_AUDIT_ENABLED=true
DBEAST_AUDIT_DIR=logs/mcp_audit

監査ファイルは日ごとの Markdown ファイルとして保存され、タイムスタンプ、ツール名、所要時間、マスクされたパラメーター、切り詰められたレスポンス、エラーが含まれます。

---

開発

pip install -e ".[dev]"
pre-commit install
pytest tests/ -v
ruff check src/ tests/
ruff format src/ tests/

オプションのローカル PostgreSQL テストデータベースを起動します。

docker compose up -d postgres

旧式の Compose：

docker-compose up -d postgres

---

ドキュメント

• SETUP.md - クライアントのセットアップ、接続シナリオ、設定、トラブルシューティングの詳細
• CONTRIBUTING.md - 開発環境のセットアップ、テスト、スタイル、コミット、PR の手順
• CODE_OF_CONDUCT.md - コミュニティガイドライン

---

ライセンス

MIT