マルチデータベースMCPサーバー
DB MCP サーバーとは何ですか?
DB MCPサーバーは、AIモデルが複数のデータベースを同時に操作するための標準化された方法を提供します。FreePeak /cortexフレームワーク上に構築されており、AIアシスタントは統一されたインターフェースを通じて、SQLクエリの実行、トランザクションの管理、スキーマの探索、そして異なるデータベースシステム間のパフォーマンス分析を行うことができます。
コアコンセプト
マルチデータベースサポート
従来のデータベース コネクタとは異なり、DB MCP サーバーは複数のデータベースに同時に接続して対話できます。
{
"connections": [
{
"id": "mysql1",
"type": "mysql",
"host": "localhost",
"port": 3306,
"name": "db1",
"user": "user1",
"password": "password1"
},
{
"id": "postgres1",
"type": "postgres",
"host": "localhost",
"port": 5432,
"name": "db2",
"user": "user2",
"password": "password2"
}
]
}
動的ツール生成
接続されたデータベースごとに、サーバーは一連の特殊なツールを自動的に生成します。
// For a database with ID "mysql1", these tools are generated:
query_mysql1 // Execute SQL queries
execute_mysql1 // Run data modification statements
transaction_mysql1 // Manage transactions
schema_mysql1 // Explore database schema
performance_mysql1 // Analyze query performance
クリーンアーキテクチャ
サーバーは、以下のレイヤーで Clean Architecture の原則に従います。
- ドメイン層: コアビジネスエンティティとインターフェース
- リポジトリ層: データアクセスの実装
- ユースケース層: アプリケーションビジネスロジック
- 配信層: 外部インターフェース (MCP ツール)
特徴
- 同時マルチデータベースサポート: 複数のMySQLおよびPostgreSQLデータベースに同時に接続して操作します。
- データベース固有のツール生成:接続されたデータベースごとに専用のツールを自動作成します。
- クリーンアーキテクチャ：関心事を明確に分離したモジュール設計
- OpenAI Agents SDK との互換性: OpenAI Agents SDK との完全な互換性により、AI アシスタントとのシームレスな統合が可能
- 動的データベースツール:
- パラメータ付きのSQLクエリを実行する
- 適切なエラー処理でデータ変更ステートメントを実行する
- セッション間でデータベーストランザクションを管理する
- データベースのスキーマと関係を調べる
- クエリのパフォーマンスを分析し、最適化の提案を受け取る
- 統合インターフェース: さまざまなデータベース タイプ間で一貫したインタラクション パターン
- 接続管理: 複数のデータベース接続のシンプルな構成
現在サポートされているデータベース
| データベース | 状態 | 特徴 |
|---|
| MySQL | ✅ フルサポート | クエリ、トランザクション、スキーマ分析、パフォーマンス分析 |
| PostgreSQL | ✅ フルサポート (v9.6-17) | クエリ、トランザクション、スキーマ分析、パフォーマンス分析 |
クイックスタート
Dockerの使用
始める最も簡単な方法は Docker を使用することです。
# Pull the latest image
docker pull freepeak/db-mcp-server:latest
# Option 1: Run with environment variables (recommended)
docker run -p 9092:9092 \
-v $(pwd)/config.json:/app/my-config.json \
-e TRANSPORT_MODE=sse \
-e CONFIG_PATH=/app/my-config.json \
freepeak/db-mcp-server
# Option 2: Override the entrypoint
docker run -p 9092:9092 \
-v $(pwd)/config.json:/app/my-config.json \
--entrypoint /app/server \
freepeak/db-mcp-server \
-t sse -c /app/my-config.json
# Option 3: Use shell to execute the command
docker run -p 9092:9092 \
-v $(pwd)/config.json:/app/my-config.json \
freepeak/db-mcp-server \
/bin/sh -c "/app/server -t sse -c /app/my-config.json"
注: コンテナーにはすでに/app/my-config.json /app/config.jsonマウントします。
プラットフォームサポート
Docker イメージは複数のプラットフォームをサポートしています。
linux/amd64 - Intel/AMD ベースのシステム (ほとんどの Linux/Windows サーバーおよびデスクトップ)linux/arm64 - ARM64 ベースのシステム (Apple Silicon Mac、ARM サーバー) 向け
プラットフォームの不一致エラー (例: 「要求されたイメージのプラットフォームが検出されたホスト プラットフォームと一致しません」) が発生した場合は、プラットフォームを明示的に指定します。
# For Intel/AMD (x86_64) systems
docker run --platform linux/amd64 -p 9092:9092 freepeak/db-mcp-server
# For ARM64 systems (like Apple Silicon Macs)
docker run --platform linux/arm64 -p 9092:9092 freepeak/db-mcp-server
ソースから
# Clone the repository
git clone https://github.com/FreePeak/db-mcp-server.git
cd db-mcp-server
# Build the server
make build
# Run the server in SSE mode
./bin/server -t sse -c config.json
サーバーの実行
サーバーは、さまざまなユースケースに合わせて複数のトランスポート モードをサポートしています。
STDIO モード (IDE 統合用)
AIコーディングアシスタントとの統合に最適:
# Run the server in STDIO mode
./server -t stdio -c config.json
出力は JSON-RPC メッセージとして stdout に送信され、ログは stderr に送られます。
カーソル統合の場合は、 .cursor/mcp.jsonに以下を追加します。
{
"mcpServers": {
"stdio-db-mcp-server": {
"command": "/path/to/db-mcp-server/server",
"args": ["-t", "stdio", "-c", "/path/to/config.json"]
}
}
}
SSE モード (サーバー送信イベント)
Web ベースのアプリケーションおよびサービスの場合:
# Run with default host (localhost) and port (9092)
./server -t sse -c config.json
# Specify a custom host and port
./server -t sse -host 0.0.0.0 -port 8080 -c config.json
イベント ストリームのhttp://localhost:9092/sseにクライアントを接続します。
Dockerコンポーズ
データベース コンテナーを備えた開発環境向けに、完全な docker-compose.yml ファイルを提供しています。
services:
db-mcp-server:
image: freepeak/db-mcp-server:latest
ports:
- "9092:9092"
volumes:
- ./config.json:/app/config.json
- ./wait-for-it.sh:/app/wait-for-it.sh
command:
[
"/bin/sh",
"-c",
"chmod +x /app/wait-for-it.sh && /app/wait-for-it.sh mysql1:3306 -t 60 && /app/wait-for-it.sh mysql2:3306 -t 60 && /app/wait-for-it.sh postgres1:5432 -t 60 && /app/wait-for-it.sh postgres3:5432 -t 60 && /app/server -t sse -c /app/config.json",
]
depends_on:
mysql1:
condition: service_healthy
mysql2:
condition: service_healthy
postgres1:
condition: service_healthy
postgres2:
condition: service_healthy
postgres3:
condition: service_healthy
mysql1:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: password
MYSQL_DATABASE: db1
MYSQL_USER: user1
MYSQL_PASSWORD: password1
MYSQL_AUTHENTICATION_PLUGIN: mysql_native_password
ports:
- "13306:3306"
volumes:
- mysql1_data:/var/lib/mysql
command: --default-authentication-plugin=mysql_native_password --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
healthcheck:
test:
[
"CMD",
"mysqladmin",
"ping",
"-h",
"localhost",
"-u",
"root",
"-ppassword",
]
interval: 5s
timeout: 5s
retries: 10
mysql2:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: password
MYSQL_DATABASE: db2
MYSQL_USER: user2
MYSQL_PASSWORD: password2
MYSQL_AUTHENTICATION_PLUGIN: mysql_native_password
ports:
- "13307:3306"
volumes:
- mysql2_data:/var/lib/mysql
command: --default-authentication-plugin=mysql_native_password --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
healthcheck:
test:
[
"CMD",
"mysqladmin",
"ping",
"-h",
"localhost",
"-u",
"root",
"-ppassword",
]
interval: 5s
timeout: 5s
retries: 10
postgres1:
image: postgres:15
environment:
POSTGRES_USER: user1
POSTGRES_PASSWORD: password1
POSTGRES_DB: db1
ports:
- "15432:5432"
volumes:
- postgres1_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U user1 -d db1"]
interval: 5s
timeout: 5s
retries: 10
postgres2:
image: postgres:17
environment:
POSTGRES_USER: user2
POSTGRES_PASSWORD: password2
POSTGRES_DB: db2
ports:
- "15433:5432"
volumes:
- postgres2_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U user2 -d db2"]
interval: 5s
timeout: 5s
retries: 10
postgres3:
image: postgres:16.3-alpine
environment:
POSTGRES_USER: screener
POSTGRES_PASSWORD: screenerpass
POSTGRES_DB: screenerdb
ports:
- "15434:5432"
volumes:
- postgres_screener_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U screener -d screenerdb"]
interval: 5s
timeout: 5s
retries: 10
volumes:
mysql1_data:
mysql2_data:
postgres1_data:
postgres2_data:
postgres_screener_data:
この docker-compose セットアップの主な機能:
- db-mcp-serverコンテナは、すべてのデータベースサービスが準備完了するまで待機してから起動します。
- 複数のデータベースタイプとバージョンが含まれています（MySQL 8.0、PostgreSQL 15、16.3、17）
- すべてのデータベースには、サーバーが接続する前に完全に初期化されていることを確認するためのヘルスチェックが含まれています。
- すべてのデータベース サービス用の永続ボリューム
- 必要に応じてデータベースに直接アクセスするためのポートを公開
セットアップでは、 wait-for-it.shスクリプトを使用して、サーバーを起動する前にすべてのデータベースサービスが完全に準備されていることを確認します。このスクリプトは、処理を進める前に TCP ホスト/ポートが利用可能かどうかを確認します。このスクリプトをプロジェクトディレクトリに含める必要があります。Docker セットアップは、このスクリプトをコンテナにマウントし、データベースの可用性を確認するために使用します。
この設定を使用するには:
# Start all services
docker-compose up -d
# Check logs
docker-compose logs -f db-mcp-server
# Stop all services
docker-compose down
config.json ファイルに、docker-compose.yml で定義されたサービスと一致する接続詳細が含まれていることを確認します。
構成
データベース構成
データベース接続を含むconfig.jsonファイルを作成します。
{
"connections": [
{
"id": "mysql1",
"type": "mysql",
"host": "mysql1",
"port": 3306,
"name": "db1",
"user": "user1",
"password": "password1",
"query_timeout": 60,
"max_open_conns": 20,
"max_idle_conns": 5,
"conn_max_lifetime_seconds": 300,
"conn_max_idle_time_seconds": 60
},
{
"id": "mysql2",
"type": "mysql",
"host": "mysql2",
"port": 3306,
"name": "db2",
"user": "user2",
"password": "password2"
},
{
"id": "postgres1",
"type": "postgres",
"host": "postgres1",
"port": 5432,
"name": "db1",
"user": "user1",
"password": "password1"
},
{
"id": "postgres2",
"type": "postgres",
"host": "postgres2",
"port": 5432,
"name": "db2",
"user": "user2",
"password": "password2"
},
{
"id": "postgres3",
"type": "postgres",
"host": "postgres3",
"port": 5432,
"name": "screenerdb",
"user": "screener",
"password": "screenerpass"
}
]
}
docker-compose セットアップを使用する場合、 host値は docker-compose.yml ファイル内のサービス名と一致する必要があることに注意してください。
コマンドラインオプション
サーバーはさまざまなコマンドライン オプションをサポートしています。
# Basic options
./server -t <transport> -c <config-file>
# Available transports: stdio, sse
# For SSE transport, additional options:
./server -t sse -host <hostname> -port <port> -c <config-file>
# Direct database configuration:
./server -t stdio -db-config '{"connections":[...]}'
# Environment variable configuration:
export DB_CONFIG='{"connections":[...]}'
./server -t stdio
利用可能なツール
接続されたデータベースごとに (例: "mysql1"、"mysql2")、サーバーは以下を作成します。
ツールの命名規則
サーバーは、次の形式に従った名前のツールを自動的に生成します。
<tool_type>_<database_id>
どこ：
<tool_type> : クエリ、実行、トランザクション、スキーマ、パフォーマンスのいずれか<database_id> : 構成で定義されたデータベースのID
ID「mysql1」を持つデータベースのツール名の例:
query_mysql1execute_mysql1transaction_mysql1schema_mysql1performance_mysql1
データベース固有のツール
query_<dbid> : 指定されたデータベースに対してSQLクエリを実行する{
"query": "SELECT * FROM users WHERE age > ?",
"params": [30]
}
execute_<dbid> : SQL文を実行する（INSERT、UPDATE、DELETE）{
"statement": "INSERT INTO users (name, email) VALUES (?, ?)",
"params": ["John Doe", "john@example.com"]
}
transaction_<dbid> : データベーストランザクションを管理する// Begin transaction
{
"action": "begin",
"readOnly": false
}
// Execute within transaction
{
"action": "execute",
"transactionId": "<from begin response>",
"statement": "UPDATE users SET active = ? WHERE id = ?",
"params": [true, 42]
}
// Commit transaction
{
"action": "commit",
"transactionId": "<from begin response>"
}
schema_<dbid> : データベーススキーマ情報を取得する{
"random_string": "dummy"
}
performance_<dbid> : クエリパフォーマンスを分析する{
"action": "analyzeQuery",
"query": "SELECT * FROM users WHERE name LIKE ?"
}
グローバルツール
list_databases : 構成されたすべてのデータベース接続を一覧表示する
例
複数のデータベースへのクエリ
// Query the first database
{
"name": "query_mysql1",
"parameters": {
"query": "SELECT * FROM users LIMIT 5"
}
}
// Query the second database
{
"name": "query_mysql2",
"parameters": {
"query": "SELECT * FROM products LIMIT 5"
}
}
トランザクションの実行
// Begin transaction
{
"name": "transaction_mysql1",
"parameters": {
"action": "begin"
}
}
// Response contains transactionId
// Execute within transaction
{
"name": "transaction_mysql1",
"parameters": {
"action": "execute",
"transactionId": "tx_12345",
"statement": "INSERT INTO orders (user_id, product_id) VALUES (?, ?)",
"params": [1, 2]
}
}
// Commit transaction
{
"name": "transaction_mysql1",
"parameters": {
"action": "commit",
"transactionId": "tx_12345"
}
}
ロードマップ
当社は、DB MCP サーバーを拡張して、幅広いデータベース システムをサポートすることに取り組んでいます。
2025年第3四半期
- MongoDB - ドキュメント指向のデータベース操作のサポート
- SQLite - 軽量な組み込みデータベース統合
- MariaDB - MySQL実装と完全に同等の機能
2025年第4四半期
- Microsoft SQL Server - T-SQL 機能を備えたエンタープライズ データベース サポート
- Oracle データベース- エンタープライズグレードの統合
- Redis - キーバリューストア操作
2026
- Cassandra - 分散型 NoSQL データベースのサポート
- Elasticsearch - 専門的な検索と分析機能
- CockroachDB - グローバル規模のアプリケーション向けの分散 SQL データベース
- DynamoDB - AWSネイティブNoSQLデータベース統合
- Neo4j - グラフデータベースのサポート
- ClickHouse - アナリティクスデータベースのサポート
トラブルシューティング
よくある問題
- 接続エラー:
config.jsonのデータベース接続設定を確認してください - ツールが見つかりません: サーバーが実行中であることを確認し、ツール名のプレフィックスを確認してください
- 失敗したクエリ: SQL構文とデータベース権限を確認してください
- Dockerボリュームマウントエラー：
mountpoint for /app/config.json: not a directoryのようなエラーが表示される場合、コンテナのそのパスに既にファイルが存在することが原因です。別のパス（例： /app/my-config.json ）にマウントし、設定を更新してください。 - Docker コマンド エラー: Docker でコマンド関連のエラーが発生した場合は、次のいずれかの方法を使用します。
- 環境変数を使用します:
-e TRANSPORT_MODE=sse -e CONFIG_PATH=/app/my-config.json - エントリポイントを上書きします:
--entrypoint /app/server freepeak/db-mcp-server -t sse -c /app/my-config.json - シェル実行を使用します:
freepeak/db-mcp-server /bin/sh -c "/app/server -t sse -c /app/my-config.json"
- Wait-for-it.sh が見つからないか動作しない: wait-for-it.sh に関連するエラーが表示される場合:
- プロジェクトディレクトリにファイルが存在することを確認してください
- 実行権限があることを確認します:
chmod +x wait-for-it.sh - 適切な行末を確認します（Windows スタイルの CRLF ではなく、Unix スタイルの LF を使用します）。
- それでも問題が解決しない場合は、代わりにサービスヘルスチェックを使用するようにdocker-compose.ymlを修正してください。
ログ
サーバーは次の場所にログを書き込みます。
- STDIO モード: stderr
- SSE モード: stdout および
./logs/db-mcp-server.log
-debugフラグを使用してデバッグ ログを有効にします。
./server -t sse -debug -c config.json
貢献
貢献を歓迎します！ご協力いただける方法は次のとおりです。
- リポジトリをフォークする
- 機能ブランチを作成する:
git checkout -b new-feature - 変更をコミットします:
git commit -am 'Add new feature' - ブランチにプッシュ:
git push origin new-feature - プルリクエストを送信する
コードが当社のコーディング標準に準拠し、適切なテストが含まれていることを確認してください。
ライセンス
このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細については LICENSE ファイルを参照してください。
サポートとお問い合わせ
カーソル統合
ツールの命名規則
MCPサーバーは、カーソルが想定する形式に一致する名前でツールを登録します。ツール名は以下の形式に従います。
mcp_<servername>_<tooltype>_<dbID>
例: mcp_mysql1_db_mcp_server_stdio_schema_mysql1_db
サーバーはデフォルトでmysql1_db_mcp_server_stdioという名前を使用します。これは、 mcp.jsonファイルの Cursor 構成と一致する必要があります。
カーソルの設定
カーソル設定 ( ~/.cursor/mcp.json ) には、次のような設定が必要です。
{
"mcpServers": {
"multidb": {
"command": "/path/to/db-mcp-server/server",
"args": ["-t", "stdio", "-c", "/path/to/database_config.json"]
}
}
}
サーバーは、構成内のデータベース識別子に一致する単純な名前を持つツールを自動的に登録します。
カーソルでのMCPツールの使用
DB MCPサーバーが起動し、Cursorで適切に設定されると、AIアシスタントとの会話でMCPツールを使用できるようになります。ツールの命名規則は以下のとおりです。
mcp_<server_name>_<tool_type>_<database_id>
どこ：
<server_name>は、.cursor/mcp.json で定義された名前です (例: "multidb")<tool_type>は、クエリ、実行、トランザクション、スキーマ、パフォーマンス、リストデータベースのいずれかです。<database_id>は、構成のデータベース ID です (list_databases には必要ありません)
例:
データベース ID が「mysql1」である「multidb」という名前のサーバーの場合:
- すべてのデータベースを一覧表示します:
mcp_multidb_list_databases
- データベースのクエリ:
mcp_multidb_query_mysql1
Query: SELECT * FROM users LIMIT 10
- データベーススキーマの表示:
mcp_multidb_schema_mysql1
- ステートメントの実行:
mcp_multidb_execute_mysql1
Statement: INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com')
- トランザクションの管理:
mcp_multidb_transaction_mysql1
Action: begin
カーソル内のMCPツールのトラブルシューティング
AI アシスタントが MCP ツールを呼び出せない場合:
- サーバーが実行中であることを確認してください（
ps aux | grep serverで確認） - .cursor/mcp.json の設定が正しいことを確認してください
- .env の server_name が MCP ツールの呼び出しと一致することを確認します。
- 設定を変更した後はカーソルを再起動してください
- エラーがないかlogs/ディレクトリのログを確認してください
OpenAIエージェントSDK統合
DB MCP サーバーは OpenAI のエージェント SDK を完全にサポートしており、データベースと直接対話できる AI エージェントを作成できます。
前���条件
- APIアクセス可能なOpenAIアカウント
- OpenAI Agents SDK がインストールされています:
pip install openai-agents - 実行中の DB MCP サーバー インスタンス (SSE モード)
基本的な統合例
DB MCP サーバーを OpenAI エージェントと統合する方法は次のとおりです。
from openai import OpenAI
from agents.agent import Agent, ModelSettings
from agents.tools.mcp_server import MCPServerSse, MCPServerSseParams
# Connect to the MCP server
db_server = MCPServerSse(
params=MCPServerSseParams(
url="http://localhost:9095/sse", # URL to your running DB MCP server
schema={
"params": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {"type": "string"},
"description": {"type": "string"},
"parameters": {"type": "object"}
}
}
}
}
),
)
# Create the agent with access to database tools
agent = Agent(
name="Database Agent",
model="gpt-4o",
model_settings=ModelSettings(temperature=0.1),
instructions="""
You are a database helper agent. You can execute SQL queries,
manage database transactions, and explore schema information.
""",
mcp_servers=[db_server],
)
# Now the agent can be used to interact with your databases through the OpenAI API
統合のテスト
リポジトリには、OpenAI Agents SDK との互換性を確認するためのテスト スクリプトが含まれています。
# Run the test script
./test_tools/openai-agent-sdk-test/run_test.sh
スクリプトは次のようになります。
- 最新の変更を加えてサーバーを構築する
- サーバーがまだ実行されていない場合は起動します
- OpenAI Agents SDKとの接続をテストする
- 統合が正しく機能しているかどうかを報告する
エージェント SDK 統合のトラブルシューティング
問題が発生した場合:
- サーバーが期待されるポートでSSEモードで実行されていることを確認します。
- OpenAI APIキーが環境変数として設定されていることを確認してください
- エージェントの指示にデータベースツールが具体的に記載されていることを確認してください
- サーバーログにエラーメッセージがないか確認します
スターの歴史
データベースクエリのタイムアウト構成
config.jsonファイルで、各データベース接続のデータベースクエリタイムアウトを設定できます。タイムアウトは秒単位で指定します。
構成例:
{
"connections": [
{
"id": "mysql1",
"type": "mysql",
"host": "mysql1",
"port": 3306,
"name": "db1",
"user": "user1",
"password": "password1",
"query_timeout": 60, // 60 seconds timeout for queries
"max_open_conns": 20,
"max_idle_conns": 5,
"conn_max_lifetime_seconds": 300,
"conn_max_idle_time_seconds": 60
}
]
}
指定されていない場合、デフォルトのクエリタイムアウトは30秒です。クエリ実行時にtimeoutパラメータ（ミリ秒単位）を指定することで、個々のクエリのタイムアウトをオーバーライドできます。
{
"tool": "query_mysql",
"params": {
"query": "SELECT * FROM large_table",
"database": "mysql1",
"timeout": 120000 // 120 seconds (overrides the database configuration)
}
}