Postgres MCP: AIエージェントをデータベースに接続する

Postgres MCPサーバーを使用すると、AIエージェントはModel Context Protocolを通じてPostgreSQLスキーマを検査し、クエリを実行できます。サーバーにデータベースの接続情報を設定すると、エージェントはそのツールを呼び出してテーブルを読み取り、データに関する質問に答えます。

このガイドでは、Postgres MCP Pro、個別のデータベースロール、および制限付きアクセスモードを使用して、Cursorをサンプルデータベースに接続します。最終結果は簡単に確認できます。エージェントは、合計月間予算が68ドルの2つのアクティブなプロジェクトを見つけるはずです。それらの行を変更しようとすると失敗するはずです。

Lizard上のManaged Postgresを使用してデータベースを作成できます。MCPプロセスはコンピューター上で実行されます。同じSQLセットアップは、所有しているローカルのPostgreSQLインスタンスでも機能します。

Postgres MCPがデータベースに接続する仕組み

エージェントはMCPサーバーにツール呼び出しを送信します。サーバーはPostgreSQLに接続し、クエリを実行して結果を返します。PostgreSQLは接続のデータベースロールの権限を確認します。

独立したオープンソースプロジェクトであるPostgres MCP Proを使用します。これは、スキーマのリスト表示、テーブルの詳細の読み取り、SQLの実行を行うツールを公開します。このセットアップではLizardがデータベースを提供します。

CursorとMCPプロセス間のローカル接続にはstdioを使用します。コンピューターはデータベースのエンドポイントに到達できる必要があります。クエリ結果はAIプロバイダーのコンテキストに入る可能性があるため、このチュートリアルでは架空のプロジェクト名と予算を使用します。

必要なもの

• 新しいPostgreSQLインスタンス、または使い捨ての個別データベース。データベースとロールを作成できる所有者アカウントが必要です。
• コンピューター上のpsql。
• 固定されたPythonパッケージを実行するuv。
• カスタムMCPサーバーが有効になっているCursor。

PostgreSQL 14.20、Python 3.12.10、postgres-mcp==0.3.0、およびmcp==1.30.0を使用して、SQLとMCPの呼び出しをテストしました。以下の結果テーブルは、それらのチェックの範囲を記録しています。

1. サンプルのPostgresデータベースを作成する

新しいLizardプロジェクトで、ダッシュボードからManaged Postgresを追加します。すでにLizard CLIを使用しており、新しいプロジェクトをリンクしている場合は、次を実行します。

lizard add postgres

ダッシュボードには、ホスト、ポート、データベース、および認証情報が表示されます。Managed Postgres接続ガイドに従って、psqlで接続します。このセットアップには所有者アカウントを使用してください。エージェントには別のアカウントが割り当てられます。

psqlで、新しいデータベースを作成して切り替えます。

CREATE DATABASE mcp_demo;
\connect mcp_demo

\connectはpsqlコマンドです。SQLエディターを使用する場合は、次のブロックを実行する前にmcp_demoを選択してください。データベース名がすでに存在する場合は、別の名前を選択し、以降の例を更新してください。

3つの行を持つテーブルを1つ作成します。

CREATE SCHEMA demo;

CREATE TABLE demo.projects (
  id integer PRIMARY KEY,
  name text NOT NULL,
  status text NOT NULL CHECK (status IN ('active', 'paused')),
  monthly_budget_usd numeric(10, 2) NOT NULL
);

INSERT INTO demo.projects VALUES
  (1, 'Atlas', 'active', 49.00),
  (2, 'Beacon', 'active', 19.00),
  (3, 'Cedar', 'paused', 0.00);

これらの金額はサンプルデータの一部です。Lizardの価格ではありません。

2. エージェントにサンプルテーブルを読み取れるロールを付与する

管理権限のないログインを作成します。

CREATE ROLE mcp_reader LOGIN
  NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOINHERIT;

次に、このpsqlコマンドを実行して、SQL履歴にパスワードを残さずにパスワードを設定します。

\password mcp_reader

以下の権限付与は、新しいmcp_demoデータベースに対するものです。PUBLICの取り消しは、そのデータベースを使用する他のロールに影響するため、このブロックを既存の共有アプリケーションデータベースに貼り付けないでください。

REVOKE ALL ON DATABASE mcp_demo FROM PUBLIC;
REVOKE CREATE ON SCHEMA public FROM PUBLIC;

GRANT CONNECT ON DATABASE mcp_demo TO mcp_reader;
GRANT USAGE ON SCHEMA demo TO mcp_reader;
GRANT SELECT ON demo.projects TO mcp_reader;

ALTER ROLE mcp_reader IN DATABASE mcp_demo
  SET default_transaction_read_only = on;
ALTER ROLE mcp_reader IN DATABASE mcp_demo
  SET statement_timeout = '5s';

これにより、1つのテーブルへのアクセスが許可されます。後で作成するテーブルには、独自の権限付与が必要です。PostgreSQLはシステムカタログを通じてオブジェクト名を公開する場合がありますが、テーブル権限は行へのアクセスを制御します。PostgreSQLのGRANTリファレンスを参照してください。

読み取り専用のデフォルト設定は間違いを防ぐのに役立ちますが、クライアントはその設定を変更できます。このロールがdemo.projectsに書き込むのを防ぐのは、テーブルの権限付与です。デフォルト設定をオフにした後でも、更新が失敗することを確認しました。

3. 読み取り専用接続をソースコードの外部に保存する

新しいロールとmcp_demoデータベースを使用して、接続URLを構築します。プロバイダーの接続手順から、ホスト、ポート、および必要なTLS設定を維持してください。パスワードをURLに含める場合は、特殊文字をパーセントエンコードします。PostgreSQLは接続URIフォーマットを文書化しています。

TLSを必要とするホスト型エンドポイントの場合、形式は次のようになります。

postgresql://mcp_reader:URL_ENCODED_PASSWORD@DB_HOST:DB_PORT/mcp_demo?sslmode=require

sslmode=requireは暗号化を必要とします。プロバイダーが完全な証明書チェックのためにCA証明書とホスト名を提供している場合は、そのverify-full構成を使用します。証明書エラーには、一致するホストと信頼構成が必要です。ホスト型接続でTLSを無効にして解決しないでください。

プロジェクトの.gitignoreに.env.mcpを追加し、プロジェクトのルートにそのファイルを作成します。

DATABASE_URI=postgresql://mcp_reader:URL_ENCODED_PASSWORD@DB_HOST:DB_PORT/mcp_demo?sslmode=require

すべてのプレースホルダーを読み取り専用接続の値に置き換えます。名前は**DATABASE_URI**です。これはPostgres MCP Proが想定しているものです。Lizardのアプリケーション接続変数の名前はDATABASE_URLです。その名前だけを渡しても、このMCPサーバーは構成されません。

所有者接続はこのファイルに含めないでください。macOSまたはLinuxでは、読み取り専用ファイルへのアクセスを制限します。

chmod 600 .env.mcp

4. CursorでPostgres MCPを構成する

同じプロジェクトに.cursor/mcp.jsonを作成します。ファイルにすでに他のサーバーが含まれている場合は、既存のmcpServersオブジェクト内にpostgres-demoを追加します。

{
  "mcpServers": {
    "postgres-demo": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--python", "3.12",
        "--with", "mcp==1.30.0",
        "--from", "postgres-mcp==0.3.0",
        "postgres-mcp", "--access-mode=restricted"
      ],
      "envFile": "${workspaceFolder}/.env.mcp"
    }
  }
}

Cursorは、プロジェクトのMCP構成と、ローカルのstdioサーバー用のenvFileをサポートしています。MCP構成リファレンスを参照してください。Cursorがuvxを見つけられない場合は、コマンドをインストールされたフルパスに置き換えてください。

2つのバージョンの固定は重要です。今回の検証では、MCP SDKの制約なしでpostgres-mcp==0.3.0をインストールすると、mcp==2.2.0が選択されました。その後、サーバーはmcp.server.fastmcpのインポートに失敗しました。mcp==1.30.0を使用すると、サーバーは起動し、以下のテストを完了しました。

データベース接続を開く前にパッケージの起動を確認するには、次を実行します。

uvx --python 3.12 --with 'mcp==1.30.0' \
  --from 'postgres-mcp==0.3.0' postgres-mcp --help

CursorのMCP設定でpostgres-demoを有効にするか、再起動します。セットアップを確認している間はツールの承認を有効にしたままにし、呼び出しを許可する前にSQL引数を検査してください。

5. ツールと回答を検証する

スキーマに関する質問から始めます。

Use postgres-demo to inspect the demo schema. List its tables and the columns
of demo.projects. Show the tool results. Do not change the database.

サーバーはlist_schemas、list_objects、get_object_details、およびexecute_sqlを公開するはずです。エージェントがツールを呼び出し、テーブルからid、name、status、およびmonthly_budget_usdを報告することを確認します。

次に、以下のように質問します。

Using demo.projects, how many projects are active and what is their total
monthly budget in USD? Show the SQL and the database result.

その回答を得るためのクエリは次のとおりです。

SELECT
  count(*) AS active_projects,
  sum(monthly_budget_usd) AS total_budget_usd
FROM demo.projects
WHERE status = 'active';

期待される値は次のとおりです。

最後に、このサンプルテーブルの制限を確認します。WHERE false条件により、クエリに一致する行がないことが保証されます。

Use execute_sql to run exactly:
UPDATE demo.projects SET name = name WHERE false;
Report the tool response. Do not retry with another tool or connection.

今回のテストでは、制限付きモードはError: Error validating queryを返しました。mcp_readerを使用した個別の直接接続では、読み取り専用のデフォルトを無効にした後でもpermission denied for table projectsが返されました。MCPのチェックとデータベースの権限付与は、それぞれ操作を拒否しました。

テストした内容

2026年9月24日に、合成データを含む新しいローカルのPostgreSQL 14.20インスタンスに対して、サンプルSQLと実際のMCP呼び出しを実行しました。Python 3.12.10、Postgres MCP Pro 0.3.0、およびMCP SDK 1.30.0を使用しました。

これらのチェックは、SQL権限とMCPプロトコルをカバーしています。このテストでは、CursorのUIフローを実行したり、新しいLizardデータベースをデプロイしたりはしていません。独自のエンドポイントに対して上記のチェックに従ってください。接続されたMCPインジケーターだけでは、データベースツールが機能することを証明できません。

一般的なPostgres MCP接続エラーの修正

PostgreSQL拡張機能は必要ですか？

このガイドのスキーマとデータのクエリには、追加の拡張機能は必要ありません。Postgres MCP Proは、異なる要件を持つパフォーマンスツールも提供しています。

そのトップクエリ分析ではpg_stat_statementsを使用します。仮想インデックス分析ではhypopgを使用します。拡張機能を利用できるか、サーバー構成とロール権限が要件を満たすかを確認してください。拡張機能の作成には、所有者のアクションまたはサーバーの変更が必要になる場合があります。これらのツールを使用する前に、プロジェクトの拡張機能の要件を確認してください。

スキーマとSELECTのチェックから始めます。チューニングツールでの拡張機能関連の失敗は、それ自体が基本的なMCP接続が壊れていることを意味するわけではありません。

よくある質問

Postgres MCPはLizard MCPと同じですか？

いいえ。この例では、Postgres MCP Proを使用してPostgreSQLデータベースにクエリを実行します。Managed Postgresはそのデータベースを提供します。コネクタは別のプロジェクトです。

別のAIエージェントを使用できますか？

はい、クライアントがstdio経由でローカルMCPサーバーをサポートしている場合に使用できます。同じバージョンに固定したプロセス、読み取り用ロールの認証情報、および制限付きモードを使用し、そのクライアントの構成フォーマットに従ってください。上記のJSONはCursor用です。

制限付きモードはデータベース権限の代わりになりますか？

両方を使用してください。制限付きモードはMCPサーバー内のクエリをチェックします。PostgreSQLの権限付与は、別のクライアント経由であっても、接続ロールが実行できることを制限します。マイグレーションと管理のために所有者アカウントを保持してください。

テーブルを作成したり、マイグレーションを実行したりしてくれますか？

このセットアップは、読み取り専用ロールにサンプルテーブルへのアクセスを許可します。アプリケーションのスキーマを作成または変更することはできません。レビュー済みのマイグレーションは、通常のアプリケーションデプロイプロセスで実行してください。

次にデータベースをアプリに接続する

エージェントがサンプルスキーマを検査し、期待される回答を返せるようになれば、開発中のデータベースに関する質問の作業基盤が整います。テーブルを追加する際は、エージェントの読み取り専用の認証情報をアプリケーションの認証情報とは別に保持してください。

プロジェクト用にManaged Postgresを作成するか、データベース接続ガイドに従うか、Cursorアプリのデプロイ例に進んでください。複数のクライアントで共有されるMCPサービスをデプロイする場合は、個別のリモートMCPサーバーガイドを参照してください。