pgvector

mcp-server-pgvector

一个 MCP 服务，让大模型 Agent 能够直接使用 PostgreSQL 中由 pgvector 支持的嵌入表：相似度搜索、混合搜索（向量 + 全文）、插入或更新，以及 HNSW/IVFFlat 索引管理。

通用 PostgreSQL MCP 服务会开放原始 SQL 或架构自省能力；本服务专门针对 pgvector，近邻搜索、距离度量和 ANN 索引调优都是一等工具，而不是需要模型手写 SQL 才能实现的功能。

工具

工具	描述
list_vector_tables	查找数据库中的每个 vector 列，并显示其维度
describe_vector_table	查看表的列、索引和近似行数
similarity_search	对向量列进行 k-NN 搜索（cosine / L2 / inner product），支持结构化元数据筛选
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 多项测试，包括维度不匹配和注入尝试的回归测试；每次推送/PR 时，都会在 CI 中使用真实的 pgvector 容器，针对 Python 3.10–3.13 运行。另有一个独立的 CI 任务负责构建软件包并对构建结果运行 twine check。
• 连接失败会以普通的 ConnectionRefusedError/asyncpg 异常形式呈现——已验证这些异常不会将 DSN 凭据泄露到错误文本中。

已知限制，如实说明：

• 没有按工具设置授权——访问控制取决于 DATABASE_URL 中 Postgres 角色的权限。如果不同 Agent 需要不同权限，请为它们提供由不同 Postgres 角色支持的不同连接字符串，而不要为同一个 DSN 运行不同的服务实例。
• 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.