pgvector

mcp-server-pgvector

LLM エージェントが、PostgreSQL の pgvector を利用した埋め込みテーブルに直接アクセスできる MCP サーバーです。類似検索、ハイブリッド検索（ベクトル検索＋全文検索）、アップサート、HNSW／IVFFlat インデックス管理に対応しています。

汎用的な Postgres MCP サーバーでは生の SQL やスキーマのイントロスペクションを提供しますが、このサーバーは pgvector に特化しています。近傍検索、距離メトリクス、ANN インデックスのチューニングを専用ツールとして利用できるため、モデルが SQL を自分で記述する必要はありません。

ツール

ツール	説明
list_vector_tables	データベース内のすべての vector カラムを、次元数とともに検出します
describe_vector_table	テーブルのカラム、インデックス、および概算行数を表示します
similarity_search	ベクトルカラムに対する k-NN 検索（コサイン／L2／内積）。構造化メタデータフィルターに対応します
hybrid_search	ベクトル類似度と Postgres 全文検索（ts_rank_cd）を重み付けして組み合わせます
upsert_embedding	行の埋め込みとメタデータを挿入または更新します
create_vector_index	パラメーターを調整可能な HNSW または IVFFlat インデックスを作成します
explain_similarity_query	類似検索クエリに対して EXPLAIN ANALYZE を実行し、ANN インデックスが使われていることを確認します

安全性

• SQL に埋め込む前に、すべてのテーブル名／カラム名を information_schema／pg_catalog と照合して検証します。そのため、LLM が参照できる識別子は、すでに存在するものに限られます。値は常にバインドパラメーターとして渡されます。
• メタデータフィルターは、許可リストで定義された {column, op, value} のみを受け付け、生の SQL 断片は受け付けません。
• MCP_PGVECTOR_READ_ONLY=true を設定すると、upsert_embedding と create_vector_index が無効になり、読み取り／検索ツールのみが利用可能になります。本番データベースに接続する場合に便利です。
• 各クエリにはコマンドごとのタイムアウト（MCP_PGVECTOR_COMMAND_TIMEOUT_SECONDS、デフォルトは 30s）が設定されているため、処理の重いクエリがプール接続を占有し、ほかのすべての呼び出しを無期限に停滞させることはありません。無効にするには 0 を設定します。

インストール

uvx mcp-server-pgvector

または pip を使用します。

pip install mcp-server-pgvector
python -m mcp_server_pgvector

設定

サーバーは接続文字列を DATABASE_URL（または PGVECTOR_DATABASE_URL）から読み込みます。

{
  "mcpServers": {
    "pgvector": {
      "command": "uvx",
      "args": ["mcp-server-pgvector"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/mydb",
        "MCP_PGVECTOR_READ_ONLY": "false",
        "MCP_PGVECTOR_COMMAND_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

本番環境への対応状況

対応済み：

• 識別子を安全に扱う SQL（使用前にすべてのテーブル名／カラム名を pg_catalog と照合）と、フィルター演算子の許可リストにより、ツール引数から生の SQL が実行される経路はありません。
• クエリごとのタイムアウトにより、処理が終わらないクエリが（5 接続の小規模な）プールを独占するのを防ぎます。
• 次元数の不一致やインジェクションの試行に対する回帰テストを含む 60 件以上のテストを、Python 3.10～3.13 で実際の pgvector コンテナーを使い、プッシュ／PR ごとに CI で実行します。別の CI ジョブではパッケージをビルドし、生成物に対して twine check を実行します。
• 接続エラーは通常の ConnectionRefusedError／asyncpg 例外として表面化します。エラーテキストに DSN の認証情報が漏れないことを確認済みです。

既知の制限事項：

• ツールごとの認可には対応していません。アクセス制御は DATABASE_URL の Postgres ロールが持つ権限に依存します。エージェントごとに異なる権限が必要な場合は、同じ DSN を使うサーバーインスタンスを分けるのではなく、異なる Postgres ロールに紐付いた別々の接続文字列を用意してください。
• hybrid_search の全文検索側では、Postgres の 'english' テキスト検索設定を固定で使用します。現時点では変更するパラメーターはありません。
• 構造化ログには対応していません。失敗は MCP のエラーチャネルを通じて例外として通知され、追跡可能なログには記録されません。単一ユーザー向けのデスクトップ MCP クライアントでは問題ありませんが、共有サービスとして実行する場合には大きな不足です。
• 接続プールは 1～5 接続に固定されており、現時点では環境変数で設定できません。

開発

uv sync --dev

# Bring up an isolated pgvector instance for local testing
docker compose -f docker-compose.dev.yml up -d

export DATABASE_URL=postgresql://postgres:postgres@localhost:5434/postgres
uv run pytest

uv run ruff check .
uv run pyright

コントリビューション

CONTRIBUTING.md を参照してください。リリース履歴については CHANGELOG.md を参照してください。

License

MIT — see LICENSE.