MCPサーバ - PostgreSQLのソースを表示

== 概要 ==
PostgreSQL MCP Server (@henkey/postgres-mcp-server) は、Model Context Protocol (MCP) を通じて、<br>
AIアシスタントがPostgreSQLデータベースと相互作用するための統合ツールインターフェースを提供するサーバである。<br>
<br>
元は46個のツールを17個に統合したメタツール設計を採用しており、効率的なデータベース操作を実現する。<br>
<br>
Claude Desktop、Claude Code、OpenCode、VS Code、Cursor等の複数のMCPクライアント環境で動作する。<br>
Windows、MacOS、Linuxの主要なOSに対応する。<br>
<br>
このサーバを使用することにより、AIアシスタントが自然言語の指示を通じてPostgreSQLのスキーマ管理、テーブル操作、クエリ実行、データベース分析、リアルタイム監視等を自動化できるようになる。<br>
<br>
主な機能カテゴリは以下の通りである。<br>
<br>
<center>
{| class="wikitable"
|+ Supabaseツール一覧
|-
! カテゴリ !! ツール数 !! 内容
|-
| メタツール || 8個 || スキーマ管理、テーブル操作、カラム管理、ENUM管理、<br>制約管理、インデックス管理、型管理、RLSポリシー管理
|-
| クエリ・ミューテーションツール || 4個 || SELECT文の実行、データ変更 (INSERT / UPDATE / DELETE)、<br>任意のSQL実行、コメント管理
|-
| 専門ツール || 5個 || データベース分析、デバッグ、データエクスポート / インポート、<br>データベース間転送、リアルタイム監視
|}
</center>
<br><br>

== PostgreSQL MCPサーバのインストール ==
==== 前提条件 ====
PostgreSQL MCP Serverを使用するために必要な前提条件を以下に示す。<br>
<br>
* Node.js
*: バージョン v18以降が必要
* PostgreSQL
*: バージョン 12以降が必要
* <code>npx</code> コマンド
*: <code>npx</code> コマンドを使用してPostgreSQL MCP Serverを実行するために必要
*: Node.jsに同梱されている。
<br>
==== npxを使用したインストール ====
<code>npx</code> コマンドを使用する場合、インストール不要でPostgreSQL MCP Serverを直接実行できる。<br>
以下に示すコマンドを実行して、PostgreSQL MCP Serverを起動する。<br>
<br>
 npx @henkey/postgres-mcp-server --connection-string "postgresql://user:password@localhost:5432/database"
<br>
MCPクライアントの設定ファイルで指定する場合は、後述の各クライアント設定を参照すること。<br>
<br>
==== npmグローバルインストール ====
npmを使用してグローバルにインストールする場合は、以下に示すコマンドを実行する。<br>
<br>
 npm install -g @henkey/postgres-mcp-server
<br>
==== Dockerを使用したインストール ====
DockerイメージはDocker Hubで公開されており、Node.jsをインストールせずにPostgreSQL MCP Serverを実行できる。<br>
<br>
以下に示すコマンドを実行する。<br>
<br>
 docker run -i --rm -e POSTGRES_CONNECTION_STRING="postgresql://user:password@localhost:5432/database" henkey/postgres-mcp:latest
<br>
==== Smithery経由のインストール ====
Smithery CLIを使用してClaude向けにインストールする場合は、以下に示すコマンドを実行する。<br>
<br>
 npx -y @smithery/cli install @HenkDz/postgresql-mcp-server --client claude
<br><br>

== MCPクライアントの設定 ==
==== Claude Desktopの設定 ====
Claude Desktopの設定ファイルの場所は以下の通りである。<br>
<br>
* Linux
*: <u>~/.config/Claude/claude_desktop_config.json</u>
* MacOS
*: <u>~/Library/Application Support/Claude/claude_desktop_config.json</u>
* Windows
*: <u>%APPDATA%\Claude\claude_desktop_config.json</u>
<br>
接続文字列を使用する場合は、設定ファイルに以下に示す内容を設定する。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "mcpServers": {
     "postgresql": {
       "command": "npx",
       "args": ["-y", "@henkey/postgres-mcp-server"],
       "env": {
         "POSTGRES_CONNECTION_STRING": "postgresql://username:password@localhost:5432/database"
       }
     }
   }
 }
 </syntaxhighlight>
<br>
Dockerを使用する場合は、設定ファイルに以下に示す内容を設定する。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "mcpServers": {
     "postgresql": {
       "command": "docker",
       "args": [
         "run", "--rm", "-i",
         "-e", "POSTGRES_CONNECTION_STRING=postgresql://username:password@host.docker.internal:5432/database",
         "henkey/postgres-mcp:latest"
       ]
     }
   }
 }
 </syntaxhighlight>
<br>
設定ファイルを保存した後、Claude Desktopを再起動して設定を反映する。<br>
<br>
==== Claude Codeの設定 ====
Claude Codeでは、<code>claude mcp add</code> コマンドを使用してPostgreSQL MCP Serverを追加できる。<br>
<br>
 claude mcp add postgresql -- npx -y @henkey/postgres-mcp-server
<br>
プロジェクトの <u>.mcp.json</u> ファイルに設定を記述する場合は、以下に示す内容を記述する。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "mcpServers": {
     "postgresql": {
       "command": "npx",
       "args": ["-y", "@henkey/postgres-mcp-server"],
       "env": {
         "POSTGRES_CONNECTION_STRING": "postgresql://username:password@localhost:5432/database"
       }
     }
   }
 }
 </syntaxhighlight>
<br>
==== OpenCodeの設定 ====
設定ファイル <u>opencode.json</u> ファイルの <code>mcpServers</code> セクションに以下に示す内容を追加する。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "mcpServers": {
     "postgresql": {
       "type": "stdio",
       "command": "npx",
       "args": ["-y", "@henkey/postgres-mcp-server"],
       "env": {
         "POSTGRES_CONNECTION_STRING": "postgresql://username:password@localhost:5432/database"
       }
     }
   }
 }
 </syntaxhighlight>
<br>
==== VS Code / Cursorの設定 ====
<u>.vscode/mcp.json</u> または <u>.cursor/mcp.json</u> ファイルに以下に示す内容を設定する。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "mcpServers": {
     "postgresql": {
       "command": "npx",
       "args": ["-y", "@henkey/postgres-mcp-server"],
       "env": {
         "POSTGRES_CONNECTION_STRING": "postgresql://username:password@localhost:5432/database"
       }
     }
   }
 }
 </syntaxhighlight>
<br><br>

== 環境変数とオプション ==
==== 環境変数一覧 ====
下表に、PostgreSQL MCP Serverの動作をカスタマイズするための環境変数を示す。<br>
<br>
<center>
{| class="wikitable"
|+ 環境変数の一覧
! 環境変数 !! 説明
|-
| <code>POSTGRES_CONNECTION_STRING</code> || PostgreSQLへの接続文字列を指定する。<br>標準のPostgreSQL URI形式を使用する。
|-
| <code>PGHOST</code> || PostgreSQLサーバのホスト名を指定する。
|-
| <code>PGPORT</code> || PostgreSQLサーバのポート番号を指定する。<br>デフォルト値は 5432
|-
| <code>PGDATABASE</code> || 接続先のデータベース名を指定する。
|-
| <code>PGUSER</code> || PostgreSQLのユーザ名を指定する。
|-
| <code>PGPASSWORD</code> || PostgreSQLのパスワードを指定する。
|-
| <code>PGSSLMODE</code> || SSL接続モードを指定する。<br><code>disable</code>、<code>allow</code>、<code>prefer</code>、<code>require</code> 等が使用できる。
|}
</center>
<br><br>

== 接続文字列 ==
==== 接続文字列の基本形式 ====
PostgreSQL MCP Serverへの接続文字列の基本形式を以下に示す。<br>
<br>
 postgresql://username:password@hostname:port/database
<br>
下表に、各パラメータの説明を示す。<br>
<br>
<center>
{| class="wikitable"
|+ 接続パラメータの一覧
! パラメータ !! 説明
|-
| <code>username</code> || PostgreSQLデータベースのユーザ名
|-
| <code>password</code> || PostgreSQLデータベースのパスワード
|-
| <code>hostname</code> || PostgreSQLサーバのホスト名またはIPアドレス
|-
| <code>port</code> || PostgreSQLサーバのポート番号 (デフォルト: 5432)
|-
| <code>database</code> || 接続先のデータベース名
|}
</center>
<br>
==== 接続文字列の例 ====
ローカル接続 (認証あり) の場合の接続文字列を以下に示す。<br>
<br>
 postgresql://username:password@localhost:5432/database
<br>
ローカル接続 (認証なし) の場合の接続文字列を以下に示す。<br>
<br>
 postgresql://localhost:5432/database
<br>
SSL接続の場合の接続文字列を以下に示す。<br>
<br>
 postgresql://username:password@hostname:5432/database?sslmode=require
<br>
複数のパラメータを指定する場合の接続文字列を以下に示す。<br>
<br>
 postgresql://username:password@hostname:5432/database?sslmode=require&connect_timeout=10&application_name=mcp_server
<br><br>

== PostgreSQL MCPサーバの機能 ==
PostgreSQL MCP Serverは、メタツール、クエリ・ミューテーションツール、専門ツールの3つのカテゴリで17個のツールを提供する。<br>
<br>
==== メタツール ====
下表に、データベーススキーマの定義・管理に関するツールを示す。<br>
<br>
<center>
{| class="wikitable"
|+ メタツールの一覧
! ツール !! 説明
|-
| schemaManagement || スキーマの作成、変更、削除を管理する。
|-
| tableOperations || テーブルの作成、変更、削除を管理する。
|-
| columnManagement || カラムの追加、変更、削除を管理する。
|-
| enumManagement || ENUM型の作成、変更、削除を管理する。
|-
| constraintManagement || 制約 (主キー、外部キー、一意制約等) の管理を行う。
|-
| indexManagement || インデックスの作成、変更、削除を管理する。
|-
| typeManagement || カスタム型の管理を行う。
|-
| policyManagement || Row Level Security (RLS) ポリシーの管理を行う。
|}
</center>
<br>
==== クエリ・ミューテーションツール ====
下表に、SQLクエリの実行およびデータ変更に関するツールを示す。<br>
<br>
<center>
{| class="wikitable"
|+ クエリ・ミューテーションツールの一覧
! ツール !! 説明
|-
| executeQuery || SELECT文を実行してデータを取得する。<br>読み取り専用クエリに使用する。
|-
| executeMutation || INSERT、UPDATE、DELETE文を実行してデータを変更する。
|-
| executeSQL || 任意のSQL文を実行する。DDL文やトランザクション制御にも使用できる。
|-
| commentsManagement || テーブル、カラム等のデータベースオブジェクトにコメントを追加・管理する。
|}
</center>
<br>
==== 専門ツール ====
下表に、データベースの分析・監視・データ転送に関するツールを示す。<br>
<br>
<center>
{| class="wikitable"
|+ 専門ツールの一覧
! ツール !! 説明
|-
| databaseAnalysis || データベースの統計情報、テーブルサイズ、インデックス使用状況等を分析する。
|-
| debugDatabase || ロック状況、実行中のクエリ、接続情報等のデバッグ情報を取得する。
|-
| dataExportImport || データのCSV / JSONエクスポートおよびインポートを行う。
|-
| crossDatabaseTransfer || 異なるデータベース間でのデータ転送を行う。
|-
| realtimeMonitoring || データベースのパフォーマンス、接続数、クエリ実行状況をリアルタイムで監視する。
|}
</center>
<br><br>

== 使用例 ==
PostgreSQL MCP Serverの各ツールは、AIアシスタントが自然言語の指示を受けて自動的に呼び出す。<br>
<br>
==== テーブル構造の確認 ====
テーブルのスキーマ情報を確認する場合の操作例を以下に示す。<br>
<br>
* usersテーブルのスキーマ情報を表示する場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 usersテーブルのスキーマ情報を表示してください。
 </syntaxhighlight>
*: <br>
<br>
==== データの検索 ====
テーブルからデータをクエリする場合の操作例を以下に示す。<br>
<br>
* 条件を指定して特定フィールドのみ取得する場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 productsテーブルから価格が1000円以降の商品の名前と価格を取得してください。
 </syntaxhighlight>
*: <br>
<br>
==== データベース分析 ====
データベースの統計情報やインデックス使用状況を分析する場合の操作例を以下に示す。<br>
<br>
* テーブルサイズとインデックス使用状況を確認する場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 データベースのテーブルサイズとインデックス使用状況を分析してください。
 </syntaxhighlight>
*: <br>
<br>
==== リアルタイム監視 ====
現在のデータベースの状態をリアルタイムで確認する場合の操作例を以下に示す。<br>
<br>
* 実行中のクエリとアクティブな接続数を確認する場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 現在実行中のクエリとアクティブな接続数を確認してください。
 </syntaxhighlight>
*: <br>
<br>
==== データのエクスポート ====
テーブルデータをファイル形式でエクスポートする場合の操作例を以下に示す。<br>
<br>
* テーブルデータをCSV形式でエクスポートする場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 ordersテーブルのデータをCSV形式でエクスポートしてください。
 </syntaxhighlight>
*: <br>
<br><br>

== その他 ==
==== セキュリティ ====
下表に、PostgreSQL MCP Serverのセキュリティに関する推奨事項を示す。<br>
<br>
<center>
{| class="wikitable"
|+ セキュリティに関する推奨事項
! 項目 !! 説明
|-
| 読み取り専用ユーザの使用 || MCPサーバ用に専用の読み取り専用PostgreSQLユーザを作成することを推奨する。<br>必要最小限の権限のみを付与すること。
|-
| 認証情報の管理 || 接続文字列やパスワード等の機密情報は、設定ファイルに直接記述せず、<br>環境変数 (<code>POSTGRES_CONNECTION_STRING</code>、<code>PGPASSWORD</code> 等) を使用して管理することを推奨する。
|-
| SSL/TLS接続の使用 || 本番環境では、接続文字列に <code>sslmode=require</code> を指定して、<br>SSL/TLS暗号化通信を有効にすることを推奨する。
|-
| ネットワークアクセスの制限 || <u>pg_hba.conf</u> でホストベース認証を設定して、信頼できるネットワーク範囲のみから接続を許可すること。
|-
| ツールアクセス制御 || MCPクライアントのツールアクセス制御機能を活用して、<br>AIアシスタントが使用できるツールを必要なものだけに制限することを推奨する。
|}
</center>
<br>
==== トラブルシューティング ====
下表に、一般的なエラーと対処法を示す。<br>
<br>
<center>
{| class="wikitable"
|+ トラブルシューティング一覧
! 問題 !! 原因 !! 対処法
|-
| 接続エラーが発生する || 接続文字列のユーザ名またはパスワードが誤っている。<br>PostgreSQLサーバが起動していない。 || 接続文字列を確認する。<br>PostgreSQLサーバの起動状態を確認する。<br><u>pg_hba.conf</u> ファイルの認証設定を確認する。
|-
| 接続できない (Connection refused) || PostgreSQLがリッスンしているポート (デフォルト: 5432) が<br>ファイアウォールでブロックされている。 || ファイアウォールの設定を確認してポート5432を開放する。<br><u>postgresql.conf</u> ファイルの <code>listen_addresses</code> を確認する。
|-
| npxコマンドが見つからない || Node.jsがインストールされていない。<br>または要件を満たすバージョンでない。 || Node.js v18以降をインストールする。
|-
| SSL接続エラーが発生する || SSL接続モードの設定が誤っている。<br>SSL証明書が無効 || 接続文字列の <code>sslmode</code> パラメータを確認する。<br>PostgreSQLサーバ側のSSL設定を確認する。
|-
| 書き込み操作が拒否される || PostgreSQLユーザに書き込み権限が付与されていない。 || PostgreSQLユーザのGRANT権限を確認する。<br>必要な場合はINSERT、UPDATE、DELETE権限を付与する。
|}
</center>
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,Electric Circuit,Electric,pcb,Mathematics,AVR,TI,STMicro,AVR,ATmega,MSP430,STM,Arduino,Xilinx,FPGA,Verilog,HDL,PinePhone,Pine Phone,Raspberry,Raspberry Pi,C,C++,C#,Qt,Qml,MFC,Shell,Bash,Zsh,Fish,SUSE,SLE,Suse Enterprise,Suse Linux,openSUSE,open SUSE,Leap,Linux,uCLnux,電気回路,電子回路,基板,プリント基板,PostgreSQL,MCP,Model Context Protocol,postgres-mcp-server,Claude,AI,MCPサーバ,データベース,スキーマ管理,クエリ,SQL
|description={{PAGENAME}} - 電子回路とSUSE Linuxに関する情報 | This page is {{PAGENAME}} in our wiki about electronic circuits and SUSE Linux
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:設定]]