Db Connect MCP

🚀 db-connect-mcp - マルチデータベースMCPサーバー

複数のデータベースシステムを横断した探索的データ分析用の読み取り専用MCP（モデルコンテキストプロトコル）サーバーです。このサーバーは、PostgreSQL、MySQL、ClickHouseデータベースに対して安全な読み取り専用アクセスを提供し、包括的な分析機能を備えています。

🚀 クイックスタート

デモ

1. インストール

   pip install db-connect-mcp
   

2. Claude Desktopのclaude_desktop_config.jsonに追加

   {
     "mcpServers": {
       "db-connect": {
         "command": "python",
         "args": ["-m", "db_connect_mcp"],
         "env": {
           "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
         }
       }
     }
   }
   

3. Claude Desktopを再起動して、データベースのクエリを開始しましょう！

⚠️ 重要提示

python -m db_connect_mcpを使用すると、PythonのScriptsディレクトリがPATHに含まれていなくてもコマンドが機能します。

✨ 主な機能

🗄️ マルチデータベースサポート

• PostgreSQL - 高度なメタデータと統計情報を含む完全なサポート
• MySQL - MySQLとMariaDBデータベースの完全なサポート
• ClickHouse - 分析ワークロードと列指向ストレージのサポート

🔍 データベース探索

• スキーマの一覧表示 - データベース内のすべてのスキーマを表示
• テーブルの一覧表示 - メタデータ（サイズ、行数、コメント）付きですべてのテーブルを表示
• テーブルの詳細表示 - 詳細な列情報、インデックス、制約を取得
• 関係の表示 - テーブル間の外部キー関係を理解

📊 データ分析

• 列のプロファイリング - 列データの統計分析
  • 基本統計（件数、一意の値、null値）
  • 数値統計（平均、中央値、標準偏差、四分位数）
  • 値の頻度分布
  • カーディナリティ分析
• データサンプリング - 構成可能な制限でテーブルデータをプレビュー
• カスタムクエリ - 安全に読み取り専用のSQLクエリを実行
• データベースのプロファイリング - ハイレベルなデータベースメトリクスと最大のテーブルを取得

🔒 セキュリティ機能

• 読み取り専用の強制 - すべての接続は複数のレベルで読み取り専用になっています
• クエリの検証 - SELECTとWITHクエリのみが許可されます
• 自動制限 - クエリは自動的に制限され、大きな結果セットを防ぎます
• 接続文字列のセキュリティ - 自動的に読み取り専用パラメータが追加されます
• データベース固有のセキュリティ - 各アダプターは適切なセキュリティ対策を実装しています

💡 ベストプラクティス

💡 使用建议

db-connect-mcpは、テーブルと列に適切なコメントが付けられたデータベースで最適に動作します。データベースに記述的なコメントが含まれている場合、MCPサーバーはAIアシスタントにより豊富なコンテキストを提供でき、データモデルの理解が向上し、より正確なクエリ提案が可能になります。

PostgreSQLでのコメントの追加

COMMENT ON TABLE users IS 'Registered user accounts with profile information';
COMMENT ON COLUMN users.email IS 'Primary email address, used for authentication';
COMMENT ON COLUMN users.is_verified IS 'Whether email has been verified via confirmation link';

MySQLでのコメントの追加

ALTER TABLE users COMMENT = 'Registered user accounts with profile information';
ALTER TABLE users MODIFY COLUMN email VARCHAR(255) COMMENT 'Primary email address, used for authentication';

サーバーは、テーブルを説明する際にこれらのコメントを自動的に取得して表示し、AIアシスタントがデータの目的とセマンティクスを理解するのに役立ちます。

🔐 SSHトンネルサポート

• 安全なリモートアクセス - SSHトンネルを介してファイアウォールの後ろにあるデータベースに接続
• 自動トンネル管理 - トンネルのライフサイクルが透過的に処理されます（起動、ヘルスチェック、再起動、クリーンアップ）
• 柔軟な認証 - パスワードまたは秘密鍵によるSSH認証
• 任意のデータベースタイプ - 同じトンネルを介してPostgreSQL、MySQL、ClickHouseと動作します

設定の詳細については、SSHトンネルガイドを参照してください。

📦 インストール

前提条件

• Python 3.10以上
• データベース：PostgreSQL (9.6+)、MySQL/MariaDB (5.7+/10.2+)、またはClickHouse

pipを使用したインストール

pip install db-connect-mcp

これでパッケージは使用可能です。

⚠️ 重要提示

開発者向け：開発環境のセットアップについては、開発ガイドを参照してください。

📚 詳細ドキュメント

設定

.envファイルを作成し、データベース接続文字列を記述します。

DATABASE_URL=your_database_connection_string_here

サーバーは自動的にデータベースタイプを検出し、適切な読み取り専用パラメータを追加します。

接続文字列の例

サーバーは、より柔軟で安全なURL処理を提供します。

• 自動ドライバー検出：指定されていない場合は、非同期ドライバーが自動的に追加されます
• JDBC URLサポート：JDBC接頭辞は自動的に処理されます
  • jdbc:postgresql://... → postgresql+asyncpg://...
  • jdbc:mysql://... → mysql+aiomysql://...
  • すべての方言バリエーションで動作します（例：jdbc:postgres://, jdbc:mariadb://）
• データベース方言のバリエーション：一般的なバリエーションは自動的に正規化されます
  • PostgreSQL: postgresql, postgres, pg, psql, pgsql
  • MySQL/MariaDB: mysql, mariadb, maria
  • ClickHouse: clickhouse, ch, click
• 許可リストベースのパラメータフィルタリング：既知の安全なパラメータのみが保持されます
• データベース固有のパラメータ：各データベースタイプには独自のサポートされるパラメータのセットがあります
• 堅牢なパース：さまざまなURL形式を適切に処理します

PostgreSQL

# シンプルなURL（ドライバーは自動的に追加されます）
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

# 一般的なバリエーション（すべてpostgresql+asyncpgに正規化されます）
DATABASE_URL=postgres://user:pass@host:5432/db  # Heroku, AWS RDSスタイル
DATABASE_URL=pg://user:pass@host:5432/db         # 短い形式
DATABASE_URL=psql://user:pass@host:5432/db       # CLIスタイル

# JDBC URL（自動的に変換されます）
DATABASE_URL=jdbc:postgresql://user:pass@host:5432/db  # Javaアプリから
DATABASE_URL=jdbc:postgres://user:pass@host:5432/db    # バリエーション付きのJDBC

# 明示的な非同期ドライバー付き
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/db

# サポートされるパラメータ付き（以下のリストを参照）
DATABASE_URL=postgres://user:pass@host:5432/db?application_name=myapp&connect_timeout=10

サポートされるPostgreSQLパラメータ

• application_name - pg_stat_activityでアプリを識別するために使用します（監視に役立ちます）
• connect_timeout - 接続タイムアウト（秒）
• command_timeout - 操作のデフォルトタイムアウト
• ssl / sslmode - SSL接続要件（asyncpg互換性のために自動的に変換されます）
• server_settings - サーバー設定の辞書
• options - サーバーに送信するコマンドラインオプション
• パフォーマンスチューニング: prepared_statement_cache_size, max_cached_statement_lifetime, など

MySQL/MariaDB

# シンプルなURL（ドライバーは自動的に追加されます）
DATABASE_URL=mysql://root:password@localhost:3306/mydb

# MariaDB URL（mysql+aiomysqlに正規化されます）
DATABASE_URL=mariadb://user:pass@host:3306/db    # MariaDBスタイル
DATABASE_URL=maria://user:pass@host:3306/db      # 短い形式

# JDBC URL（自動的に変換されます）
DATABASE_URL=jdbc:mysql://user:pass@host:3306/db     # Javaアプリから
DATABASE_URL=jdbc:mariadb://user:pass@host:3306/db   # JDBC MariaDB

# 明示的な非同期ドライバー付き
DATABASE_URL=mysql+aiomysql://user:pass@host:3306/db

# 文字セット付き（適切なUnicodeサポートには重要です）
DATABASE_URL=mariadb://user:pass@remote.host:3306/db?charset=utf8mb4

サポートされるMySQLパラメータ

• charset - 文字エンコーディング（例：utf8mb4） - データの整合性に重要
• use_unicode - Unicodeサポートを有効にする
• connect_timeout, read_timeout, write_timeout - さまざまなタイムアウト
• autocommit - トランザクションの自動コミットモード
• init_command - 実行する初期SQLコマンド
• sql_mode - SQLモード設定
• time_zone - タイムゾーン設定

ClickHouse

# シンプルなURL（ドライバーは自動的に追加されます）
DATABASE_URL=clickhouse://default:@localhost:9000/default

# 短い形式（clickhouse+asynchに正規化されます）
DATABASE_URL=ch://user:pass@host:9000/db         # 短い形式
DATABASE_URL=click://user:pass@host:9000/db      # 代替形式

# JDBC URL（自動的に変換されます）
DATABASE_URL=jdbc:clickhouse://user:pass@host:9000/db  # Javaアプリから
DATABASE_URL=jdbc:ch://user:pass@host:9000/db         # 短い形式のJDBC

# 明示的な非同期ドライバー付き
DATABASE_URL=clickhouse+asynch://user:pass@host:9000/db

# パフォーマンス設定付き
DATABASE_URL=ch://user:pass@host:9000/db?timeout=60&max_threads=4

サポートされるClickHouseパラメータ

• database - デフォルトのデータベース選択
• timeout, connect_timeout, send_receive_timeout - さまざまなタイムアウト
• compress, compression - 圧縮を有効にする
• max_block_size, max_threads -パフォーマンスチューニング

⚠️ 重要提示

• SSLパラメータ (ssl, sslmode) は、asyncpgに適した形式に自動的に変換されます
• 証明書ファイルパラメータ (sslcert, sslkey, sslrootcert) は、互換性の問題を引き起こす可能性があるため、フィルタリングされます
• 非同期ドライバーで動作することが知られているパラメータのみが保持されます

💻 使用例

サーバーの実行

# サーバーを実行（どこでも動作し、PATHの設定は必要ありません）
python -m db_connect_mcp

# 環境変数付きで実行
DATABASE_URL="postgresql://user:pass@host:5432/db" python -m db_connect_mcp

⚠️ 重要提示

python -m db_connect_mcpを使用すると、PythonのScriptsディレクトリがPATHに含まれていなくても動作します。

Claude Codeでの使用

MCPサーバーをプロジェクトの.mcp.jsonに追加します。

claude mcp add --transport stdio db-connect --scope project \
  --env DATABASE_URL=postgresql://user:pass@host:5432/db \
  -- python -m db_connect_mcp

または、プロジェクトのルートに.mcp.jsonを手動で作成します。以下は、サポートされる各データベースの例です。

PostgreSQL

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@host:5432/mydb"
      }
    }
  }
}

MySQL

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "mysql+aiomysql://user:pass@host:3306/mydb"
      }
    }
  }
}

ClickHouse

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "clickhouse+asynch://default:@host:9000/default"
      }
    }
  }
}

SSHトンネルを介したPostgreSQL（ファイアウォールの後ろにあるデータベースで、バスティオンホストを介してのみ到達可能）

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@db-internal:5432/mydb",
        "SSH_HOST": "bastion.example.com",
        "SSH_PORT": "22",
        "SSH_USERNAME": "deployer",
        "SSH_PRIVATE_KEY_PATH": "/home/user/.ssh/id_rsa"
      }
    }
  }
}

SSHトンネルを介したMySQL

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "mysql+aiomysql://user:pass@db-internal:3306/mydb",
        "SSH_HOST": "bastion.example.com",
        "SSH_PORT": "22",
        "SSH_USERNAME": "deployer",
        "SSH_PASSWORD": "secret"
      }
    }
  }
}

複数のデータベース（各MCPサーバーインスタンスは1つのデータベースに接続します）

{
  "mcpServers": {
    "postgres-prod": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@pg-host:5432/prod"
      }
    },
    "mysql-analytics": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "mysql+aiomysql://user:pass@mysql-host:3306/analytics"
      }
    }
  }
}

.mcp.jsonを作成した後、Claude Codeを再起動し、/mcpで確認します。利用可能なすべてのツールとともにdb-connect-mcpが表示されるはずです。

💡 使用建议

SSH_PRIVATE_KEY_PATHの代わりにSSH_PRIVATE_KEYを使用すると、秘密鍵の内容を文字列（生のPEMまたはBase64エンコードされたPEM）として直接渡すことができます。これは、キーファイルのマウントが実用的でないCI/CDまたはクラウド環境で役立ちます。

トンネルの完全な設定については、SSHトンネルガイドを参照してください。

Claude Desktopでの使用

サーバーをClaude Desktopの設定 (claude_desktop_config.json) に追加します。

{
  "mcpServers": {
    "db-connect": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@host:5432/db"
      }
    }
  }
}

Claude Codeの例で示されている同じデータベースURL形式とSSHトンネル環境変数は、Claude Desktopでも同じように機能します。

⚠️ 重要提示

開発用：uvを使用してソースから実行する方法については、開発ガイドを参照してください。

データベース機能サポート

利用可能なツール

list_schemas

データベース内のすべてのスキーマをリストします。

list_tables

スキーマ内のすべてのテーブルをメタデータ付きでリストします。

• パラメータ:
  • schema (オプション): スキーマ名 (デフォルト: "public")

describe_table

テーブルに関する詳細情報を取得します。

• パラメータ:
  • table_name: テーブル名
  • schema (オプション): スキーマ名 (デフォルト: "public")

analyze_column

列の統計と分布を分析します。

• パラメータ:
  • table_name: テーブル名
  • column_name: 列名
  • schema (オプション): スキーマ名 (デフォルト: "public")

sample_data

テーブルからデータのサンプルを取得します。

• パラメータ:
  • table_name: テーブル名
  • schema (オプション): スキーマ名 (デフォルト: "public")
  • limit (オプション): 行数 (デフォルト: 100, 最大: 1000)

execute_query

読み取り専用のSQLクエリを実行します。

• パラメータ:
  • query: SQLクエリ (SELECTまたはWITHである必要があります)
  • limit (オプション): 最大行数 (デフォルト: 1000, 最大: 10000)

get_table_relationships

スキーマ内の外部キー関係を取得します。

• パラメータ:
  • schema (オプション): スキーマ名 (デフォルト: "public")

Claudeでの使用例

設定が完了すると、Claudeでサーバーを使用できます。

"Can you analyze my database and tell me about the table structure?"
"Show me the relationships between tables in the public schema"
"What's the distribution of values in the users.created_at column?"
"Give me a sample of data from the orders table"
"Run this query: SELECT COUNT(*) FROM users WHERE created_at > '2024-01-01'"

データベース固有の例

PostgreSQLでの操作

"List all schemas except system ones"
"Show me the foreign key relationships in the sales schema"
"Analyze the performance of indexes on the products table"

MySQLでの操作

"What storage engines are being used in my database?"
"Show me all tables in the information_schema"
"Analyze the customer_orders table structure"

ClickHouseでの操作

"Show me the partitions for the events table"
"What's the compression ratio for the analytics.clicks table?"
"Sample 1000 rows from the metrics table"

🔧 技術詳細

セキュリティと安全性

• 設計上の読み取り専用：サーバーは複数のレベルで読み取り専用アクセスを強制します。
  • 接続文字列パラメータ
  • セッションレベルの設定
  • クエリ検証
• データの変更なし：INSERT、UPDATE、DELETE、CREATE、DROPなどの変更ステートメントはブロックされます。
• クエリ制限：すべてのクエリは自動的に制限され、過度のリソース使用を防ぎます。
• 機密操作なし：システムカタログや管理機能へのアクセスはありません。

開発

詳細な開発セットアップ、テスト、および貢献ガイドラインについては、開発ガイドを参照してください。

プロジェクト構造

db-connect-mcp/
├── src/
│   └── db_connect_mcp/
│       ├── adapters/         # データベース固有のアダプター
│       │   ├── __init__.py
│       │   ├── base.py      # 基本アダプターインターフェース
│       │   ├── postgresql.py # PostgreSQLアダプター
│       │   ├── mysql.py     # MySQLアダプター
│       │   └── clickhouse.py # ClickHouseアダプター
│       ├── core/            # コア機能
│       │   ├── __init__.py
│       │   ├── connection.py # データベース接続管理
│       │   ├── executor.py  # クエリ実行
│       │   ├── inspector.py # メタデータ検査
│       │   ├── analyzer.py  # 統計分析
│       │   └── tunnel.py   # SSHトンネル管理
│       ├── models/          # データモデル
│       │   ├── __init__.py
│       │   ├── capabilities.py # データベース機能
│       │   ├── config.py    # 設定モデル
│       │   ├── database.py  # データベースモデル
│       │   ├── query.py     # クエリモデル
│       │   ├── statistics.py # 統計モデル
│       │   └── table.py     # テーブルメタデータモデル
│       ├── __init__.py
│       ├── __main__.py      # モジュールエントリポイント
│       └── server.py        # メインMCPサーバー実装
├── tests/
│   ├── unit/            # 単体テスト（モック）
│   ├── module/          # モジュールテスト（単一コンポーネント + データベース）
│   ├── integration/     # 統合テスト（フルスタック）
│   └── conftest.py      # 共有フィクスチャ
├── .env.example         # 環境設定の例
├── pyproject.toml      # プロジェクト依存関係とコンソールスクリプト
└── README.md          # このファイル

アーキテクチャ

サーバーは、複数のデータベースシステムをサポートするためにアダプターパターンを使用しています。

• アダプター：各データベースタイプには、データベース固有の機能を実装する独自のアダプターがあります。
• コア：接続管理、クエリ実行、およびメタデータ検査のための共有機能。
• モデル：型安全と検証のためのPydanticモデル。
• サーバー：リクエストを適切なコンポーネントにルーティングするMCPサーバーの実装。

テストの実行

# ローカルテストデータベースを起動（サンプルデータ付きのPostgreSQL 17）
cd tests/docker && docker-compose up -d && cd ../..

# すべてのテストを並列で実行（推奨 - 6ワーカー）
uv run pytest -n 6

# 特定のテストモジュールを実行
uv run pytest tests/module/test_inspector.py -v -n 6
uv run pytest tests/integration/ -v -n 6

# テストデータベースを停止
cd tests/docker && docker-compose down && cd ../..

# データベースをリセット（新しいデータでクリーンな状態に）
cd tests/docker && docker-compose down -v && docker-compose up -d && cd ../..

ローカルテストデータベース

• 7つのテーブルにわたる50,000件以上のサンプルデータを持つPostgreSQL 17
• Docker Composeを介して自動的に初期化されます
• クラウドデータベースまたは.env設定は必要ありません
• 詳細については、Dockerセットアップを参照してください。

詳細なテスト手順については、開発ガイドおよびテストガイドを参照してください。

トラブルシューティング

接続問題

• DATABASE_URLが正しく、適切なドライバーが含まれていることを確認してください。
• データベースへのネットワーク接続を確認してください。
• データベースユーザーが適切な読み取り権限を持っていることを確認してください。
• PostgreSQLの場合：SSLが必要かどうかを確認してください (?ssl=require)。
• MySQLの場合：文字セット設定を確認してください (?charset=utf8mb4)。
• ClickHouseの場合：ポートを確認してください（ネイティブの場合はデフォルトが9000、HTTPの場合は8123）。

データベース固有の問題

PostgreSQL

• 非同期操作にはasyncpgドライバーを指定することを確認してください。
• クラウドデータベースにはSSL証明書が必要な場合があります。

MySQL/MariaDB

• 非同期サポートにはaiomysqlドライバーを使用してください。
• MySQLのバージョン互換性を確認してください（5.7+またはMariaDB 10.2+）。
• 文字セットと照合順序の設定を確認してください。

ClickHouse

• 非同期操作にはasynchドライバーを使用してください。
• ClickHouseは外部キーと制約のサポートが制限されていることに注意してください。
• 一部の統計関数が利用できない場合があります。

権限エラー

• データベースユーザーは、分析したいスキーマ/テーブルに少なくともSELECT権限が必要です。
• 一部の統計関数には追加の権限が必要な場合があります。
• ClickHouseはシステムテーブルに対して特定の権限が必要な場合があります。

大きな結果セット

• limitパラメータを使用して結果サイズを制御してください。
• サーバーは自動的に結果を制限し、メモリの問題を防ぎます。
• 大規模な分析の場合は、より具体的なクエリを使用することを検討してください。

貢献

貢献は大歓迎です！サーバーはデフォルトで読み取り専用かつ安全に設計されています。新しい機能は、これらの安全保証を維持する必要があります。

📄 ライセンス

MITライセンス - 詳細については、LICENSEファイルを参照してください。