MCPサーバ - PostgreSQL

提供: MochiuWiki : SUSE, EC, PCB

概要

PostgreSQL MCP Server (@henkey/postgres-mcp-server) は、Model Context Protocol (MCP) を通じて、
AIアシスタントがPostgreSQLデータベースと相互作用するための統合ツールインターフェースを提供するサーバである。

元は46個のツールを17個に統合したメタツール設計を採用しており、効率的なデータベース操作を実現する。

Claude Desktop、Claude Code、OpenCode、VS Code、Cursor等の複数のMCPクライアント環境で動作する。
Windows、MacOS、Linuxの主要なOSに対応する。

このサーバを使用することにより、AIアシスタントが自然言語の指示を通じてPostgreSQLのスキーマ管理、テーブル操作、クエリ実行、データベース分析、リアルタイム監視等を自動化できるようになる。

主な機能カテゴリは以下の通りである。

Supabaseツール一覧
カテゴリ ツール数 内容
メタツール 8個 スキーマ管理、テーブル操作、カラム管理、ENUM管理、
制約管理、インデックス管理、型管理、RLSポリシー管理
クエリ・ミューテーションツール 4個 SELECT文の実行、データ変更 (INSERT / UPDATE / DELETE)、
任意のSQL実行、コメント管理
専門ツール 5個 データベース分析、デバッグ、データエクスポート / インポート、
データベース間転送、リアルタイム監視



PostgreSQL MCPサーバのインストール

前提条件

PostgreSQL MCP Serverを使用するために必要な前提条件を以下に示す。

  • Node.js
    バージョン v18以降が必要
  • PostgreSQL
    バージョン 12以降が必要
  • npx コマンド
    npx コマンドを使用してPostgreSQL MCP Serverを実行するために必要
    Node.jsに同梱されている。


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

npx コマンドを使用する場合、インストール不要でPostgreSQL MCP Serverを直接実行できる。
以下に示すコマンドを実行して、PostgreSQL MCP Serverを起動する。

npx @henkey/postgres-mcp-server --connection-string "postgresql://user:password@localhost:5432/database"


MCPクライアントの設定ファイルで指定する場合は、後述の各クライアント設定を参照すること。

npmグローバルインストール

npmを使用してグローバルにインストールする場合は、以下に示すコマンドを実行する。

npm install -g @henkey/postgres-mcp-server


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

DockerイメージはDocker Hubで公開されており、Node.jsをインストールせずにPostgreSQL MCP Serverを実行できる。

以下に示すコマンドを実行する。

docker run -i --rm -e POSTGRES_CONNECTION_STRING="postgresql://user:password@localhost:5432/database" henkey/postgres-mcp:latest


Smithery経由のインストール

Smithery CLIを使用してClaude向けにインストールする場合は、以下に示すコマンドを実行する。

npx -y @smithery/cli install @HenkDz/postgresql-mcp-server --client claude



MCPクライアントの設定

Claude Desktopの設定

Claude Desktopの設定ファイルの場所は以下の通りである。

  • Linux
    ~/.config/Claude/claude_desktop_config.json
  • MacOS
    ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows
    %APPDATA%\Claude\claude_desktop_config.json


接続文字列を使用する場合は、設定ファイルに以下に示す内容を設定する。

 {
   "mcpServers": {
     "postgresql": {
       "command": "npx",
       "args": ["-y", "@henkey/postgres-mcp-server"],
       "env": {
         "POSTGRES_CONNECTION_STRING": "postgresql://username:password@localhost:5432/database"
       }
     }
   }
 }


Dockerを使用する場合は、設定ファイルに以下に示す内容を設定する。

 {
   "mcpServers": {
     "postgresql": {
       "command": "docker",
       "args": [
         "run", "--rm", "-i",
         "-e", "POSTGRES_CONNECTION_STRING=postgresql://username:password@host.docker.internal:5432/database",
         "henkey/postgres-mcp:latest"
       ]
     }
   }
 }


設定ファイルを保存した後、Claude Desktopを再起動して設定を反映する。

Claude Codeの設定

Claude Codeでは、claude mcp add コマンドを使用してPostgreSQL MCP Serverを追加できる。

claude mcp add postgresql -- npx -y @henkey/postgres-mcp-server


プロジェクトの .mcp.json ファイルに設定を記述する場合は、以下に示す内容を記述する。

 {
   "mcpServers": {
     "postgresql": {
       "command": "npx",
       "args": ["-y", "@henkey/postgres-mcp-server"],
       "env": {
         "POSTGRES_CONNECTION_STRING": "postgresql://username:password@localhost:5432/database"
       }
     }
   }
 }


OpenCodeの設定

設定ファイル opencode.json ファイルの mcpServers セクションに以下に示す内容を追加する。

 {
   "mcpServers": {
     "postgresql": {
       "type": "stdio",
       "command": "npx",
       "args": ["-y", "@henkey/postgres-mcp-server"],
       "env": {
         "POSTGRES_CONNECTION_STRING": "postgresql://username:password@localhost:5432/database"
       }
     }
   }
 }


VS Code / Cursorの設定

.vscode/mcp.json または .cursor/mcp.json ファイルに以下に示す内容を設定する。

 {
   "mcpServers": {
     "postgresql": {
       "command": "npx",
       "args": ["-y", "@henkey/postgres-mcp-server"],
       "env": {
         "POSTGRES_CONNECTION_STRING": "postgresql://username:password@localhost:5432/database"
       }
     }
   }
 }



環境変数とオプション

環境変数一覧

下表に、PostgreSQL MCP Serverの動作をカスタマイズするための環境変数を示す。

環境変数の一覧
環境変数 説明
POSTGRES_CONNECTION_STRING PostgreSQLへの接続文字列を指定する。
標準のPostgreSQL URI形式を使用する。
PGHOST PostgreSQLサーバのホスト名を指定する。
PGPORT PostgreSQLサーバのポート番号を指定する。
デフォルト値は 5432
PGDATABASE 接続先のデータベース名を指定する。
PGUSER PostgreSQLのユーザ名を指定する。
PGPASSWORD PostgreSQLのパスワードを指定する。
PGSSLMODE SSL接続モードを指定する。
disable、allow、prefer、require 等が使用できる。



接続文字列

接続文字列の基本形式

PostgreSQL MCP Serverへの接続文字列の基本形式を以下に示す。

postgresql://username:password@hostname:port/database


下表に、各パラメータの説明を示す。

接続パラメータの一覧
パラメータ 説明
username PostgreSQLデータベースのユーザ名
password PostgreSQLデータベースのパスワード
hostname PostgreSQLサーバのホスト名またはIPアドレス
port PostgreSQLサーバのポート番号 (デフォルト: 5432)
database 接続先のデータベース名


接続文字列の例

ローカル接続 (認証あり) の場合の接続文字列を以下に示す。

postgresql://username:password@localhost:5432/database


ローカル接続 (認証なし) の場合の接続文字列を以下に示す。

postgresql://localhost:5432/database


SSL接続の場合の接続文字列を以下に示す。

postgresql://username:password@hostname:5432/database?sslmode=require


複数のパラメータを指定する場合の接続文字列を以下に示す。

postgresql://username:password@hostname:5432/database?sslmode=require&connect_timeout=10&application_name=mcp_server



PostgreSQL MCPサーバの機能

PostgreSQL MCP Serverは、メタツール、クエリ・ミューテーションツール、専門ツールの3つのカテゴリで17個のツールを提供する。

メタツール

下表に、データベーススキーマの定義・管理に関するツールを示す。

メタツールの一覧
ツール 説明
schemaManagement スキーマの作成、変更、削除を管理する。
tableOperations テーブルの作成、変更、削除を管理する。
columnManagement カラムの追加、変更、削除を管理する。
enumManagement ENUM型の作成、変更、削除を管理する。
constraintManagement 制約 (主キー、外部キー、一意制約等) の管理を行う。
indexManagement インデックスの作成、変更、削除を管理する。
typeManagement カスタム型の管理を行う。
policyManagement Row Level Security (RLS) ポリシーの管理を行う。


クエリ・ミューテーションツール

下表に、SQLクエリの実行およびデータ変更に関するツールを示す。

クエリ・ミューテーションツールの一覧
ツール 説明
executeQuery SELECT文を実行してデータを取得する。
読み取り専用クエリに使用する。
executeMutation INSERT、UPDATE、DELETE文を実行してデータを変更する。
executeSQL 任意のSQL文を実行する。DDL文やトランザクション制御にも使用できる。
commentsManagement テーブル、カラム等のデータベースオブジェクトにコメントを追加・管理する。


専門ツール

下表に、データベースの分析・監視・データ転送に関するツールを示す。

専門ツールの一覧
ツール 説明
databaseAnalysis データベースの統計情報、テーブルサイズ、インデックス使用状況等を分析する。
debugDatabase ロック状況、実行中のクエリ、接続情報等のデバッグ情報を取得する。
dataExportImport データのCSV / JSONエクスポートおよびインポートを行う。
crossDatabaseTransfer 異なるデータベース間でのデータ転送を行う。
realtimeMonitoring データベースのパフォーマンス、接続数、クエリ実行状況をリアルタイムで監視する。



使用例

PostgreSQL MCP Serverの各ツールは、AIアシスタントが自然言語の指示を受けて自動的に呼び出す。

テーブル構造の確認

テーブルのスキーマ情報を確認する場合の操作例を以下に示す。

  • usersテーブルのスキーマ情報を表示する場合 
     # プロンプト例 :
 
 usersテーブルのスキーマ情報を表示してください。


データの検索

テーブルからデータをクエリする場合の操作例を以下に示す。

  • 条件を指定して特定フィールドのみ取得する場合 
     # プロンプト例 :
 
 productsテーブルから価格が1000円以降の商品の名前と価格を取得してください。


データベース分析

データベースの統計情報やインデックス使用状況を分析する場合の操作例を以下に示す。

  • テーブルサイズとインデックス使用状況を確認する場合 
     # プロンプト例 :
 
 データベースのテーブルサイズとインデックス使用状況を分析してください。


リアルタイム監視

現在のデータベースの状態をリアルタイムで確認する場合の操作例を以下に示す。

  • 実行中のクエリとアクティブな接続数を確認する場合 
     # プロンプト例 :
 
 現在実行中のクエリとアクティブな接続数を確認してください。


データのエクスポート

テーブルデータをファイル形式でエクスポートする場合の操作例を以下に示す。

  • テーブルデータをCSV形式でエクスポートする場合 
     # プロンプト例 :
 
 ordersテーブルのデータをCSV形式でエクスポートしてください。



その他

セキュリティ

下表に、PostgreSQL MCP Serverのセキュリティに関する推奨事項を示す。

セキュリティに関する推奨事項
項目 説明
読み取り専用ユーザの使用 MCPサーバ用に専用の読み取り専用PostgreSQLユーザを作成することを推奨する。
必要最小限の権限のみを付与すること。
認証情報の管理 接続文字列やパスワード等の機密情報は、設定ファイルに直接記述せず、
環境変数 (POSTGRES_CONNECTION_STRING、PGPASSWORD 等) を使用して管理することを推奨する。
SSL/TLS接続の使用 本番環境では、接続文字列に sslmode=require を指定して、
SSL/TLS暗号化通信を有効にすることを推奨する。
ネットワークアクセスの制限 pg_hba.conf でホストベース認証を設定して、信頼できるネットワーク範囲のみから接続を許可すること。
ツールアクセス制御 MCPクライアントのツールアクセス制御機能を活用して、
AIアシスタントが使用できるツールを必要なものだけに制限することを推奨する。


トラブルシューティング

下表に、一般的なエラーと対処法を示す。

トラブルシューティング一覧
問題 原因 対処法
接続エラーが発生する 接続文字列のユーザ名またはパスワードが誤っている。
PostgreSQLサーバが起動していない。		 接続文字列を確認する。
PostgreSQLサーバの起動状態を確認する。
pg_hba.conf ファイルの認証設定を確認する。
接続できない (Connection refused) PostgreSQLがリッスンしているポート (デフォルト: 5432) が
ファイアウォールでブロックされている。		 ファイアウォールの設定を確認してポート5432を開放する。
postgresql.conf ファイルの listen_addresses を確認する。
npxコマンドが見つからない Node.jsがインストールされていない。
または要件を満たすバージョンでない。		 Node.js v18以降をインストールする。
SSL接続エラーが発生する SSL接続モードの設定が誤っている。
SSL証明書が無効		 接続文字列の sslmode パラメータを確認する。
PostgreSQLサーバ側のSSL設定を確認する。
書き込み操作が拒否される PostgreSQLユーザに書き込み権限が付与されていない。 PostgreSQLユーザのGRANT権限を確認する。
必要な場合はINSERT、UPDATE、DELETE権限を付与する。



「https://mochiu.net/index.php?title=MCPサーバ_-_PostgreSQL&oldid=14611」から取得