PostgreSQL操作控制层

pgsql-mcp

A controlled PostgreSQL operations layer for Model Context Protocol clients.

pgsql-mcp gives MCP clients safe PostgreSQL inspection, bounded SQL, reviewed changes, and operational diagnostics.

The server starts in restricted mode. Write tools require an explicit unrestricted configuration.

Why use pgsql-mcp

Safety boundary

Use a dedicated PostgreSQL role with the minimum required privileges.

Use stdio for local clients when possible. Put remote transports behind authentication and transport encryption.

Read the security model before production use.

Quick start

Set a read-only database URI.

DATABASE_URI='postgresql://readonly_user:password@localhost:5432/app' \
uvx pgsql-mcp

Use unrestricted mode only for a controlled environment.

DATABASE_URI='postgresql://developer:password@localhost:5432/app_dev' \
uvx pgsql-mcp --access-mode=unrestricted

Do not use a production owner or superuser role.

MCP configuration

{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": ["pgsql-mcp"],
      "env": {
        "DATABASE_URI": "postgresql://readonly_user:password@localhost:5432/app"
      }
    }
  }
}

Docker

docker run -i --rm \
  -e DATABASE_URI='postgresql://readonly_user:password@host.docker.internal:5432/app' \
  pgsql-mcp

Server profiles

Capability map

Catalog and diagnostics

• Inspect schemas, relations, routines, types, privileges, policies, and partitions.
• Search trusted PostgreSQL catalogs.
• Report installed and available extension profiles.
• Inventory objects that belong to an installed extension.
• Report PostGIS columns and spatial indexes.
• Report pgvector columns and indexes.
• Report provider capabilities without reading secrets.
• Inspect replication topology and failover readiness.

SQL and data

• Execute one bounded read-only SQL statement.
• Bind values with native PostgreSQL parameters.
• Select typed pages with stable keyset pagination.
• Insert, upsert, update, and delete rows with commit guards.
• Execute guarded atomic transactions in unrestricted mode.

Reviewed operations

• Create and hash transactional migration plans.
• Apply and roll back reviewed migrations.
• Create and hash nontransactional maintenance plans.
• Apply maintenance and reconcile an unknown outcome.

Analysis

• Explain validated queries.
• Read bounded workload statistics.
• Analyze query and workload index opportunities.
• Run database health checks.
• Publish privacy-preserving runtime metrics.

Hard limits

Protected operations also apply query, lock, and idle-transaction timeouts.

Production use

The current release scope is ready for trusted internal and operator workflows when all checklist items are true.

• Use a dedicated database role.
• Keep restricted mode unless a reviewed write workflow is required.
• Keep remote transports behind authentication and TLS.
• Set explicit row and timeout limits.
• Monitor the main branch quality jobs.
• Test each upgrade against a disposable PostgreSQL database.
• Review production readiness before deployment.

Future roadmap items are not release guarantees. Read the project plan for planned work.

Documentation

Development

uv sync --all-extras
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest -v
python scripts/check_ste_docs.py .

Run the complete gates locally before merge. GitHub Actions run only after a commit reaches main.

Read CONTRIBUTING.md before you change the project.

Release

Main branch jobs build and validate the package and container. They do not publish artifacts.

Read PUBLISHING.md for the manual release procedure.

License

MIT