Simple PostgreSQL MCP Server

シンプルな PostgreSQL MCP サーバー

これは、独自の MCP サーバーを構築したい方向けのテンプレートプロジェクトです。理解や応用がとても簡単になるように設計しており、コードは分かりやすく、すぐに使い始められるよう MCP のドキュメントも添付しています。

MCP とは？

要するに、AI 向けのプラグインを作成する方法です

Model Context Protocol（MCP）は、LLM が外部のツールやデータを利用するための標準的な方法です。簡単に言うと、次のとおりです。

• ツールを使うと、LLM はコマンド（データベースクエリの実行など）を実行できます
• リソースは、会話に添付できるデータです（プロンプトにファイルを添付するなど）
• プロンプトは、一貫性のある LLM 向けの指示を生成するテンプレートです

機能

この PostgreSQL MCP サーバーには、次の機能が実装されています。

1. ツール

   • execute_query - データベースに対して SQL クエリを実行します
   • test_connection - データベース接続が機能していることを確認します

2. リソース

   • db://tables - スキーマ内のすべてのテーブルの一覧
   • db://tables/{table_name} - 特定のテーブルのスキーマ情報
   • db://schema - データベース内のすべてのテーブルの完全なスキーマ情報

3. プロンプト

   • クエリ生成テンプレート
   • 分析クエリの作成ツール
   • このリポジトリ内のテンプレートに基づいています

前提条件

• Python 3.8+
• uv - 最新の Python パッケージマネージャーおよびインストーラー
• npx（Node.js に含まれています）
• 接続可能な PostgreSQL データベース

クイックセットアップ

1. 仮想環境を作成し、依存関係をインストールします：

   # Create a virtual environment with uv
   uv venv
   
   # Activate the virtual environment
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   
   # Install dependencies
   uv pip install -r requirements.txt
   

2. MCP Inspector を使ってサーバーを実行します：

   # Replace with YOUR actual database credentials
   npx @modelcontextprotocol/inspector uv --directory . run postgres -e DSN=postgresql://username:password@hostname:port/database -e SCHEMA=public
   

   注：npx を初めて実行する場合、インストールの承認を求められます。続行するには「y」と入力してください。

   このコマンドを実行すると、ブラウザーで MCP Inspector のインターフェースが起動します。次のようなメッセージが表示されます。

   MCP Inspector is up and running at http://localhost:5173
   

   ブラウザーが自動的に開かない場合は、URL をコピーしてブラウザーに貼り付けてください。次のような画面が表示されます。

3. Inspector を使用する：

   • インターフェースの「Connect」ボタンをクリックします（左下のコンソールにエラーメッセージが表示されている場合を除きます）
   • 「Tools」、「Resources」、「Prompts」タブを確認し、利用可能な機能を確認します
   • 一覧表示されたコマンドをクリックするか、リソース名を入力して、リソースとプロンプトを取得してみます
   • このインターフェースでは、クエリをテストし、MCP サーバーの応答を確認できます

4. 公式ドキュメントを確認する

   公式サーバー開発者ガイド：https://modelcontextprotocol.io/quickstart/server

   Inspector の詳細：https://modelcontextprotocol.io/docs/tools/inspector

AI ツールをサーバーに接続する

MCP 設定ファイルを作成すると、AI アシスタント用に MCP サーバーを設定できます。

{
   "mcpServers": {
      "postgres": {
         "command": "/path/to/uv",
         "args": [
            "--directory",
            "/path/to/simple-psql-mcp",
            "run",
            "postgres"
         ],
         "env": {
            "DSN": "postgresql://username:password@localhost:5432/my-db",
            "SCHEMA": "public"
         }
      }
   }
}

または、付属のスクリプトを使ってこの設定ファイルを生成できます。

# Make the script executable
chmod +x generate_mcp_config.sh

# Run the configuration generator
./generate_mcp_config.sh

プロンプトが表示されたら、PostgreSQL DSN とスキーマ名を入力してください。

使い方

これで、LLM に自然な言葉でデータについて質問できます。

• 「データベース内のテーブルをすべて教えて」
• 「作成日が新しいユーザーを上位 5 人表示して」
• 「州ごとの住所数を数えて」

テストには、Claude Desktop が MCP をネイティブにサポートしており、ツール、リソース、プロンプトのすべての機能をすぐに利用できます。

サンプルデータベース（任意）

データベースをまだ用意していない場合や、接続に問題がある場合は、付属のサンプルデータベースを使用できます。

# Make the script executable
chmod +x example-db/create-db.sh

# Run the database setup script
./example-db/create-db.sh

このスクリプトは、サンプルのユーザーと住所のテーブルがあらかじめ設定された PostgreSQL データベースを含む Docker コンテナーを作成します。実行後は、次の方法で接続できます。

npx @modelcontextprotocol/inspector uv --directory . run postgres -e DSN=postgresql://postgres:postgres@localhost:5432/user_database -e SCHEMA=public

次のステップ

独自の MCP サーバーでこのプロジェクトを拡張するには、次の手順に従います。

1. /src の下に新しいディレクトリを作成します（例：/src/my-new-mcp）
2. PostgreSQL の例に沿って MCP サーバーを実装します
3. pyproject.toml に新しい MCP を追加します。

[project.scripts]
postgres = "src.postgres:main"
my-new-mcp = "src.my-new-mcp:main"

その後、次のコマンドで新しい MCP を実行できます。

npx @modelcontextprotocol/inspector uv --directory . run my-new-mcp

ドキュメント

• LLM 開発を簡単にするため、MCP のドキュメントを含めています
• 次のアプローチに基づいています：https://modelcontextprotocol.io/tutorials/building-mcp-with-llms

セキュリティ

これは、開発者が独自の MCP サーバーを作成できるようにすることを目的とした実験的なプロジェクトです。試したときにすぐに動かなくならないよう最低限の対策はしていますが、ご注意ください。このツールでは簡単に SQL インジェクションを実行できてしまいます。サーバーはクエリが SELECT で始まるかどうかを確認しますが、それ以外については何も保証されません。要約すると、あなたが創業者で、なおかつ有料クライアントがいない場合を除き、本番環境では実行しないでください。

ライセンス

MIT