PostgreSQL MCP Server

PostgreSQL MCP サーバー

中文 | English

PostgreSQL データベースを操作するためのツールを提供する Model Context Protocol（MCP）サーバーです。AI アシスタントが MCP プロトコルを介して SQL クエリの実行、ステートメントの説明、テーブルの作成、データベーステーブルの一覧表示を行えるようにします。

✨ 特長

• AI によるデータベース操作： LLM が構造化されたプロトコルを通じてデータベース操作を実行できるようにします。
• 安全なツールセット： 読み取り操作と書き込み操作を、個別に承認できるツール（read_query、write_query）に分離します。
• スキーマ管理： テーブルの作成（create_table）と一覧表示（list_tables）ができます。
• クエリ分析： クエリの実行計画を分析するツールを提供します（explain_query）。
• 複数のトランスポートモード： stdio、Server-Sent Events（sse）、streamableHttp に対応し、クライアントと柔軟に連携できます。
• 環境変数による設定： .env ファイルを使って簡単に設定できます。

🛠️ 利用可能なツール

サーバーは、MCP クライアントが呼び出せる次のツールを公開します。

ツール名	説明	パラメーター
read_query	SELECT SQL クエリを実行します。	query（string、必須）：実行する SELECT ステートメント。
write_query	INSERT、UPDATE、または DELETE SQL クエリを実行します。	query（string、必須）：実行する INSERT/UPDATE/DELETE ステートメント。
create_table	CREATE TABLE SQL ステートメントを実行します。	schema（string、必須）：CREATE TABLE ステートメント。
list_tables	データベース内のユーザーが作成したすべてのテーブルを一覧表示します。	schema（string、任意）：テーブルを絞り込むスキーマ名。
explain_query	指定された SQL クエリの実行計画を返します。	query（string、必須）：説明対象のクエリ（EXPLAIN で始まる必要があります）。

🚀 クイックスタート

前提条件

• Go 1.23 以降
• PostgreSQL データベースサーバー

インストール

1. リポジトリをクローンします。

   git clone https://github.com/leixiaotian1/pgsql-mcp-server.git
   cd pgsql-mcp-server
   

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

   go mod download
   

3. MCP サーバーをビルドします。

   go build -o pgsql-mcp-server
   

設定

pg-mcp-server では、環境変数を使ってデータベースの接続情報を指定する必要があります。プロジェクトのルートに .env ファイルを作成し、次の変数を設定します。

DB_HOST=localhost      # PostgreSQL server host
DB_PORT=5432           # PostgreSQL server port
DB_NAME=postgres       # Database name
DB_USER=your_username  # Database user
DB_PASSWORD=your_pass  # Database password
DB_SSLMODE=disable     # SSL mode (disable, require, verify-ca, verify-full)
SERVER_MODE=stdio      # Server mode (stdio, sse, streamableHttp)

使用方法

サーバーの実行

./pgsql-mcp-server

MCP の設定

このサーバーを MCP 対応の AI アシスタントで使用するには、MCP の設定に以下を追加します。

{
  "mcpServers": {
    "pgsql-mcp-server": {
      "command": "/path/to/pgsql-mcp-server",
      "args": [],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "postgres",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_SSLMODE": "disable",
        "SERVER_MODE": "stdio"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

---

Docker のデプロイ

クリックして Docker のデプロイガイドを展開

前提条件

• Docker がインストールされていること

デプロイ手順

1. プロジェクトをクローンする

   git clone https://github.com/leixiaotian1/pgsql-mcp-server.git
   cd pgsql-mcp-server
   

2. .env ファイルを設定する

   プロジェクトのルートディレクトリに .env ファイルを作成します。このファイルにはデータベース接続情報を保存します。DB_HOST の値が、後で起動するデータベースコンテナ名と一致していることを確認してください。

   DB_HOST=postgres
   DB_PORT=5432
   DB_NAME=postgres
   DB_USER=user
   DB_PASSWORD=password
   DB_SSLMODE=disable
   SERVER_MODE=sse
   

3. Docker ネットワークを作成する

   アプリケーションコンテナとデータベースコンテナ間の通信を可能にするため、共有 Docker ネットワークを作成します。このコマンドは一度だけ実行する必要があります。

   docker network create sql-mcp-network
   

4. PostgreSQL データベースコンテナを起動する

   このコマンドを使って PostgreSQL コンテナを起動し、ネットワークに接続します。

   注意：

   • --name postgres：コンテナ名です。.env ファイルの DB_HOST と完全に一致させる必要があります。
   • --network sql-mcp-network：共有ネットワークに接続します。
   • -p 5432:5432：ホストの 5432 ポートをコンテナの 5432 ポートに割り当てます。これにより、パソコンから（たとえば DBeaver を使って）localhost:5432 経由で接続でき、アプリケーションコンテナは内部ネットワーク経由で 5432 ポートに直接アクセスできます。

   docker run -d \
     --name postgres \
     --network sql-mcp-network \
     -e POSTGRES_USER=user \
     -e POSTGRES_PASSWORD=password \
     -e POSTGRES_DB=postgres \
     -p 5432:5432 \
     postgres
   

5. アプリケーションをビルドして実行する

   ここからは Makefile のコマンドを使ってアプリケーションを管理できます。

   • イメージをビルドしてコンテナを実行する：

     make build
     make run
     

     これにより、古いコンテナが自動的に停止され、新しいイメージがビルドされて、新しいコンテナが起動します。

   • アプリケーションのログを表示する：

     make logs
     

     Successfully connected to database と表示されれば、正常に動作しています。

   • アプリケーションを停止する：

     make stop
     

---

🔌 サーバーモード

SERVER_MODE 環境変数を設定して、トランスポートプロトコルを選択できます。

stdio

サーバーは標準入力と標準出力を介して通信します。これがデフォルトのモードで、ローカルでのテストやコマンドラインベースの MCP クライアントとの直接連携に適しています。

sse

サーバーは Server-Sent Events（SSE）を使って通信します。このモードを有効にすると、サーバーが HTTP サービスを起動し、接続を待ち受けます。

• SSE エンドポイント： http://localhost:8088/sse
• メッセージエンドポイント： http://localhost:8088/message

streamableHttp

サーバーは Streamable HTTP トランスポートを使用します。これは、MCP 向けのより最新で柔軟な HTTP ベースのトランスポートです。

• エンドポイント： http://localhost:8088/mcp

🤝 コントリビューション

コントリビューションを歓迎します！バグを見つけた場合、機能のリクエストや改善の提案がある場合は、Pull Request を送信するか、Issue を作成してください。

1. プロジェクトをフォークします。
2. フィーチャーブランチを作成します（git checkout -b feature/AmazingFeature）。
3. 変更をコミットします（git commit -m 'Add some AmazingFeature'）。
4. ブランチにプッシュします（git push origin feature/AmazingFeature）。
5. Pull Request を作成します。

📄 ライセンス

このプロジェクトはオープンソースで、MIT ライセンスの下でライセンスされています。