pgvector MCP server

mcp-server-pgvector

<!-- mcp-name: io.github.mittalpk/pgvector -->

An MCP server that gives LLM agents first-class access to pgvector-backed embedding tables in PostgreSQL: similarity search, hybrid (vector + full-text) search, upserts, and HNSW/IVFFlat index management.

Generic Postgres MCP servers expose raw SQL or schema introspection; this one speaks pgvector specifically — nearest-neighbor search, distance metrics, and ANN index tuning are first-class tools, not something the model has to hand-write SQL for.

Tools

Safety

interpolated into SQL — an LLM can only ever reference identifiers that already exist. Values are always bound parameters.

• Every table/column name is validated against informationschema / pgcatalog before being

leaving only read/search tools available — useful when pointing the server at a production database.

• Metadata filters are a closed {column, op, value} allowlist, not a raw SQL fragment.
• Set MCPPGVECTORREADONLY=true to disable upsertembedding and createvectorindex,

30s) so one expensive query can't occupy a pool connection — and stall every other caller — indefinitely. Set it to 0 to disable.

• Every query runs with a per-command timeout (MCPPGVECTORCOMMANDTIMEOUTSECONDS, default

Installation

uvx mcp-server-pgvector

Or with pip:

pip install mcp-server-pgvector
python -m mcp_server_pgvector

Configuration

The server reads its connection string from DATABASEURL (or PGVECTORDATABASE_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"
      }
    }
  }
}

Production readiness

Covered:

filter-operator allowlist — no path from tool arguments to raw SQL.

• Identifier-safe SQL (every table/column checked against pg_catalog before use) and a closed

push/PR against a real pgvector container across Python 3.10–3.13. A separate CI job builds the package and runs twine check on the result.

• Per-query timeout, so one runaway query can't monopolize the (small, 5-connection) pool.
• 60+ tests, including dimension-mismatch and injection-attempt regressions, run in CI on every

these don't leak the DSN's credentials into error text.

• Connection failures surface as plain ConnectionRefusedError/asyncpg exceptions — verified

Shortened. The full README is on GitHub.