MCP Database Server

mcp-db-server

自然言語によるクエリに対応し、リレーショナルデータベース（PostgreSQL／MySQL）を AI エージェントに公開する MCP（Model Context Protocol）サーバーです。自然言語の質問を SQL クエリに変換し、構造化された結果を取得できます。

機能

• マルチデータベース対応：PostgreSQL と MySQL で動作します
• 自然言語から SQL へ：HuggingFace transformers を使用して、通常の英語のクエリを SQL に変換します
• RESTful API：データベース操作のための、FastAPI ベースのシンプルなエンドポイントを提供します
• 安全性を最優先：クエリの検証と結果数の制限を備えた読み取り専用の操作です
• Docker 対応：Docker Compose による完全なコンテナ化に対応しています
• 本番環境対応：ヘルスチェック、ロギング、エラー処理を備えています
• AI エージェントに最適：AI エージェントとの連携に特化して設計されています

バージョン 1.4.0 の変更点

• すべてのデータベース HTTP エンドポイントに必須の X-API-Key 認証を追加しました。ヘルスチェック用の /health は引き続き公開されています。
• 認証情報付きの無制限な CORS を削除し、許可するオリジンを明示的に設定できるようにしました。
• HTTP のデフォルトバインドアドレスを 127.0.0.1 に変更しました。
• テーブルルート経由の SQL インジェクションを防ぐため、既存のデータベーステーブルに対するテーブル名の検証を追加しました。
• asyncpg 接続で PostgreSQL の sslmode=require との互換性を追加しました。
• 安全な API キー設定に対応するため、Docker Compose、環境変数の例、ドキュメントを更新しました。
• Docker イメージを公開しました：
  • souhardyak/mcp-db-server:1.4.0
  • souhardyak/mcp-db-server:latest
• 次のイメージを GitHub Container Registry に公開する機能を追加しました：
  • ghcr.io/souhar-dya/mcp-db-server:1.4.0
  • ghcr.io/souhar-dya/mcp-db-server:latest

API エンドポイント

エンドポイント	メソッド	説明
/health	GET	ヘルスチェックとサービスの状態
/mcp/list_tables	GET	利用可能なすべてのテーブルと列数を一覧表示
/mcp/describe/{table_name}	GET	特定のテーブルのスキーマ詳細を取得
/mcp/query	POST	自然言語クエリを実行
/mcp/tables/{table_name}/sample	GET	テーブルのサンプルデータを取得

クイックスタート

オプション 1：Docker Compose（推奨）

1. クローンしてサービスを起動します：

   git clone https://github.com/Souhar-dya/mcp-db-server.git
   cd mcp-db-server
   export MCP_API_KEY="$(openssl rand -hex 32)"
   docker-compose up --build
   

2. エンドポイントをテストします：

   # Health check
   curl http://localhost:8000/health
   
   # List tables (requires the configured API key)
   curl -H "X-API-Key: $MCP_API_KEY" http://localhost:8000/mcp/list_tables
   
   # Describe a table
   curl -H "X-API-Key: $MCP_API_KEY" http://localhost:8000/mcp/describe/customers
   
   # Natural language query
   curl -X POST "http://localhost:8000/mcp/query" \
     -H "X-API-Key: $MCP_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"nl_query": "show top 5 customers by total orders"}'
   

オプション 2：ローカル開発

1. 前提条件：

   • Python 3.11+
   • PostgreSQL または MySQL データベース

2. 依存関係をインストールします：

   pip install -r requirements.txt
   

3. 環境変数を設定します：

   export DATABASE_URL="postgresql+asyncpg://user:password@localhost:5432/dbname"
   export MCP_API_KEY="$(openssl rand -hex 32)"
   # or for MySQL:
   # export DATABASE_URL="mysql+pymysql://user:password@localhost:3306/dbname"
   

4. サーバーを実行します：

   python -m app.server
   

サンプルデータベース

このプロジェクトには、現実的な e コマースデータを含むサンプルデータベースが付属しています：

• customers：顧客情報（サンプル顧客 10 件）
• orders：注文記録（サンプル注文 17 件）
• order_items：注文ごとの個別商品
• order_summary：注文データと顧客データを組み合わせたビュー

自然言語クエリの例

このサーバーは、さまざまな種類の自然言語クエリを理解できます：

# Get all customers
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "show all customers"}'

# Count orders by status
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "count orders by status"}'

# Top customers by order value
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "top 5 customers by total order amount"}'

# Recent orders
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "show recent orders from last week"}'

設定

環境変数

変数	説明	デフォルト
DATABASE_URL	データベース接続 URL 全体	postgresql+asyncpg://postgres:postgres@localhost:5432/postgres
DB_HOST	データベースのホスト	localhost
DB_PORT	データベースのポート	5432
DB_USER	データベースのユーザー名	postgres
DB_PASSWORD	データベースのパスワード	postgres
DB_NAME	データベース名	postgres
HOST	サーバーのホスト	127.0.0.1
PORT	サーバーのポート	8000
MCP_API_KEY	データベースの HTTP ルートに必要な API キー	未設定（API は無効）
CORS_ALLOW_ORIGINS	許可するブラウザーのオリジン（カンマ区切り）	空（無効）

データベース接続の例

# PostgreSQL
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mydb

# MySQL
DATABASE_URL=mysql+pymysql://user:pass@localhost:3306/mydb

# PostgreSQL with SSL
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mydb?sslmode=require

### Database Connection Examples

```bash
# PostgreSQL (local or cloud)
DATABASE_URL=postgresql+asyncpg://user:password@host:5432/dbname

# MySQL (local or cloud)
DATABASE_URL=mysql+aiomysql://user:password@host:3306/dbname

# PostgreSQL with SSL (cloud, e.g. Neon, Supabase, Aiven)
DATABASE_URL=postgresql+asyncpg://user:password@host:5432/dbname?sslmode=require

# MySQL with SSL (cloud, e.g. Aiven, PlanetScale)
DATABASE_URL=mysql+aiomysql://user:password@host:3306/dbname?ssl-mode=REQUIRED

注：

• MySQL のクラウドプロバイダーでは、URL 内の ssl-mode パラメーターはドライバーによって無視されますが、クラウド接続では MCP サーバーで SSL が常に有効になります。
• PostgreSQL のクラウド DB では sslmode=require を使用してください。MySQL では標準の URL を使用するだけで構いません。SSL は自動的に処理されます。
• ssl-mode または sslmode に関するエラーが表示された場合は、URL を確認し、正しいドライバーのプレフィックス（mysql+aiomysql または postgresql+asyncpg）を使用していることを確認してください。

クラウドデータベースの例

# Neon (PostgreSQL)
DATABASE_URL=postgresql+asyncpg://username:[email protected]/dbname

# Aiven (MySQL)
DATABASE_URL=mysql+aiomysql://avnadmin:[email protected]:11079/defaultdb?ssl-mode=REQUIRED

クラウド DB を使用した Docker の利用

docker run -d \
  -p 8000:8000 \
  -e DATABASE_URL="<your_cloud_database_url>" \
  -e MCP_API_KEY="<your_random_api_key>" \
  souhardyak/mcp-db-server:latest

GitHub Container Registry も利用できます：

docker login ghcr.io
docker pull ghcr.io/souhar-dya/mcp-db-server:latest
docker run -d \
  -p 8000:8000 \
  -e DATABASE_URL="<your_database_url>" \
  -e MCP_API_KEY="$MCP_API_KEY" \
  ghcr.io/souhar-dya/mcp-db-server:latest

v*.*.* タグをプッシュすると、イメージが自動的に公開されます。このワークフローでは、対応する GitHub Release も作成されます。v1.4.0 などの既存のタグを公開するには、ワークフローの Run workflow アクションを開き、1.4.0 を入力してください。認証なしでプルできるようにする場合は、リポジトリの Packages 設定で GHCR パッケージの公開範囲を Public に設定してください。

トラブルシューティング

• connect() got an unexpected keyword argument 'ssl-mode' が表示された場合は、無視してください。SSL は引き続き有効です。
• ネットワークエラーが発生した場合は、ファイアウォールと DB の認証情報を確認してください。
• MySQL の非同期処理をサポートするには、URL で必ず mysql+aiomysql を使用してください。

### PostgreSQL SSL connection note

For PostgreSQL cloud providers, use an asyncpg URL and `sslmode=require`:

```bash
DATABASE_URL=postgresql+asyncpg://user:password@host:5432/dbname?sslmode=require

サーバーは sslmode=require を、asyncpg が必要とする ssl オプションに正規化します。互換性のあるクラウドデータベースに対して、CREATE、INSERT、SELECT、UPDATE、DELETE、DROP を使用した一時的な PostgreSQL の検証が正常に完了しました。テストデータは保持していません。実際のパスワードを含む接続 URL をコミットしたり、共有したりしないでください。

API キー認証

MCP_API_KEY は、生成してサーバーに設定する秘密情報です。リクエストヘッダー X-API-Key を通じて、すべてのデータベース HTTP エンドポイントを保護します。コンテナーのヘルスチェックに使用する /health エンドポイントは、引き続き公開されます。

Linux または macOS で強力なキーを生成します：

export MCP_API_KEY="$(openssl rand -hex 32)"

Windows PowerShell でキーを生成します：

$bytes = New-Object byte[] 32
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
$env:MCP_API_KEY = ([BitConverter]::ToString($bytes) -replace "-", "").ToLower()

キーを指定して Docker イメージを起動します：

docker run -d \
  -p 8000:8000 \
  -e DATABASE_URL="<your_database_url>" \
  -e MCP_API_KEY="$MCP_API_KEY" \
  souhardyak/mcp-db-server:latest

同じキーを使って、保護されたエンドポイントを呼び出します：

curl -H "X-API-Key: $MCP_API_KEY" http://localhost:8000/mcp/list_tables

キーはパスワードマネージャーまたはデプロイ用のシークレットストアに保管してください。Git にコミットしたり、公開イメージに含めたり、ログに記録したりしないでください。

セキュリティ機能

• 必須のHTTP認証：データベースAPIルートではX-API-Keyが必要です。/healthはヘルスチェック用に公開されたままです
• 安全なネットワークのデフォルト設定：HTTPモードでは、明示的に別の設定をしない限り127.0.0.1にバインドします
• 制限付きCORS：オリジンを明示的に設定しない限り、クロスオリジンアクセスは無効です
• 読み取り専用操作：SELECTクエリのみ許可されます
• クエリの検証：危険なSQL操作を自動的に検出してブロックします
• 結果の制限：クエリごとに最大50行（設定可能）
• 入力のサニタイズ：SQLインジェクションを防止します
• 安全なデフォルト設定：初期状態から安全な構成になっています

アーキテクチャ

mcp-db-server/
├── app/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # FastAPI application and endpoints
│   ├── db.py                # Database connection and operations
│   └── nl_to_sql.py         # Natural language to SQL conversion
├── .github/workflows/
│   └── docker-publish.yml   # CI/CD pipeline
├── docker-compose.yml       # Docker Compose configuration
├── Dockerfile               # Container definition
├── init_db.sql             # Sample database schema and data
├── requirements.txt         # Python dependencies
└── README.md               # This file

Model Context Protocol (MCP) との統合

このサーバーは、MCP対応のAIエージェントとシームレスに連携するよう設計されています。

1. 標準化されたエンドポイント：MCPの規約に準拠したRESTful API
2. 構造化されたレスポンス：AIでの利用に最適化されたJSONレスポンス
3. エラー処理：一貫したエラーメッセージとステータスコード
4. ドキュメント：OpenAPI/Swaggerドキュメントを/docsで利用できます

VS Code MCP Store（レジストリ）への公開

VS Code MCPギャラリーでは、MCP Registryのメタデータが使用されます。このリポジトリには、レジストリへの公開用としてserver.jsonが含まれています。

1) Dockerイメージをビルドして公開する

docker build -t souhardyak/mcp-db-server:1.3.1 .
docker push souhardyak/mcp-db-server:1.3.1

2) サーバーメタデータを検証する

server.jsonは、OCIパッケージとstdioトランスポート用に構成されています。

• name：io.github.Souhar-dya/mcp-db-server
• registryType：oci
• identifier：docker.io/souhardyak/mcp-db-server:1.3.1

Dockerfileには、レジストリの所有者を示すアノテーションが含まれています。

• io.modelcontextprotocol.server.name=io.github.Souhar-dya/mcp-db-server

3) MCP Registryに公開する

パブリッシャーをインストールし、メタデータを公開します。

mcp-publisher login github
mcp-publisher publish

公開後は、VS CodeのMCP機能など、レジストリを参照するMCP対応クライアントから検索・インストールできます。

4) VS Codeのローカル設定例

{
  "servers": {
    "mcp-db-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "DATABASE_URL=sqlite+aiosqlite:////data/default.db",
        "souhardyak/mcp-db-server:1.3.1"
      ]
    }
  }
}

Dockerスモークテスト

tests/dockerにある専用のDockerスモークテストを使用します。

python tests/docker/smoke_test.py

このテストでは、Dockerデーモンへのアクセス、イメージのビルド、コンテナの起動、ヘルスステータスを検証します。

デプロイ

Docker Hub

# Pull the latest image
docker pull souhardyak/mcp-db-server:latest

# Run with your database
docker run -d \
  -p 8000:8000 \
  -e DATABASE_URL="your_database_url_here" \
  souhardyak/mcp-db-server:latest

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-db-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-db-server
  template:
    metadata:
      labels:
        app: mcp-db-server
    spec:
      containers:
        - name: mcp-db-server
          image: souhardyak/mcp-db-server:latest
          ports:
            - containerPort: 8000
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: url
---
apiVersion: v1
kind: Service
metadata:
  name: mcp-db-server-service
spec:
  selector:
    app: mcp-db-server
  ports:
    - port: 80
      targetPort: 8000
  type: LoadBalancer

テスト

ローカルでテストを実行する

# Start test database
docker-compose up postgres -d

# Wait for database to be ready
sleep 10

# Run tests
python -m pytest tests/ -v

手動テスト

# Test health endpoint
curl http://localhost:8000/health

# Test table listing
curl http://localhost:8000/mcp/list_tables

# Test natural language query
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "show me all customers from California"}'

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

ライセンス

このプロジェクトはApache License 2.0の下でライセンスされています。詳細はLICENSEファイルをご覧ください。

📝 変更履歴

v1.3.0 (2025-12-24) - Dockerのパス修正

• 修正：Dockerコンテナ内のインポートパスの問題を解決しました。これにより、from db import DatabaseManagerが失敗していました
• 修正：Dockerfileとdocker-compose.ymlのヘルスチェックで、相対パスを絶対パスに変更しました
• 改善：mcp_server.pyで堅牢なパス解決を使用するようになり、ローカル環境とDockerコンテナの両方で動作するようになりました
• 更新：すべてのパス修正を含むDockerイメージを再ビルドしてプッシュしました

v1.2.0 (2025-11-03) - MySQLのカラムアクセス修正

• 修正：MySQLデータベースで発生するCould not locate column in row for column 'column_name'エラーを解決しました
• 修正：SQLAlchemyとの互換性を高めるため、describe_tableメソッドでインデックスベースの行アクセスを使用するように変更しました
• 改善：スキーマのイントロスペクションにおけるデータベース間の互換性を強化しました
• 解決：GitHub Issue #1

v1.1.0 (2025-09-28) - 非同期処理のバグ修正

• 修正：MCPサーバーで発生するstr can't be used in 'await' expressionエラーを解決しました
• 改善：NLPクエリ処理がClaude Desktopとの統合で正しく動作するようになりました
• 強化：包括的なテスト用データベースセットアップスクリプトを追加しました
• 更新：バグ修正と依存関係の更新を含むDockerイメージを再ビルドしました

v1.0.0 (2025-09-25) - 初回リリース

• 初回：MCP データベースサーバーの完全な実装
• 追加：FastAPI を使用した RESTful API
• 追加：自然言語から SQL への変換
• 追加：Docker によるコンテナ化とデプロイ
• 追加：複数のデータベースをサポート（PostgreSQL、MySQL、SQLite）

謝辞

• 優れた Web フレームワークを提供する FastAPI
• 自然言語から SQL への変換機能を提供する HuggingFace Transformers
• データベース抽象化を提供する SQLAlchemy
• Model Context Protocol（MCP）コミュニティ

サポート

• 問題を報告
• ディスカッション
• ドキュメント

---

⭐ このプロジェクトがお役に立った場合は、ぜひスターを付けてください！