home / mcp / postgres mcp server

Postgres MCP Server

Provides safe, read-controlled access to PostgreSQL with NL queries, schema introspection, and guarded write operations.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "arktechnwa-postgres-mcp": {
      "command": "node",
      "args": [
        "/path/to/postgres-mcp/dist/index.js"
      ],
      "env": {
        "PGHOST": "localhost",
        "PGUSER": "readonly_user",
        "PGDATABASE": "myapp",
        "PGPASSWORD": "secret",
        "ANTHROPIC_API_KEY": "sk-..."
      }
    }
  }
}

You run a PostgreSQL MCP server that safely exposes your database for natural-language queries and controlled SQL execution. It provides schema visibility, guarded read/write access, and reliability features so your AI assistant can help you explore and modify data without risking your data.

How to use

You interact with the PostgreSQL MCP server through an MCP client. Start with a config that restricts access to read-only by default, then grant write or admin permissions only when you truly need them. Use the natural language interface to ask questions in plain English and receive generated SQL along with results. When you want to execute changes, use the write-enabled or admin modes that you explicitly enable.

How to install

Prerequisites: Node.js 18+ and PostgreSQL 12+. You may optionally provide an Anthropic API key for AI-powered NL→SQL features.

npm install -g @arktechnwa/postgres-mcp

Configuration and usage notes

Set up MCP servers to run locally or remotely. You can configure a local stdio server that runs a Node-based MCP, or a CLI-style server that executes the postgres-mcp binary. Use environment variables to pass your database credentials and any API keys.

Example local stdio server setup (two approaches shown in code snippets): one using Node to run the MCP index, and one using the postgres-mcp CLI executable.

Additional considerations

Security: use a read-only database user by default. Blacklist sensitive schemas and columns. Enforce a statement timeout and row limits to prevent runaway queries. Do not log credentials or reveal connection strings.

Troubleshooting and tips

If you encounter timeouts or degraded health, check circuit-breaker status and ensure your pool size is appropriate for your workload. Review the row limits and filtering rules to avoid unintended large queries.

Notes on capability and behavior

The server supports read operations by default and writes only when explicitly permitted. It introspects the schema without exposing data, and it includes mechanisms to prevent long-running or dangerous queries.

Available tools

pg_query

Execute a SELECT query and return results with metadata such as row_count and execution_time.

pg_execute

Execute INSERT/UPDATE/DELETE statements with optional RETURNING and track affected_rows.

pg_ask

Ask a question in natural language and translate it to SQL, returning generated SQL and results. Supports fallback mode when API key is not provided.

pg_tables

List tables with metadata such as schema, name, type, row_estimate, and description.

pg_columns

Get column information for a specific table, including data types and constraints.

pg_indexes

Get index information for tables.

pg_constraints

Get constraint information (PRIMARY KEY, FOREIGN KEY, UNIQUE, CHECK) for a table.

pg_schema

Return complete schema for a table, including columns, indexes, and constraints.

pg_sample

Return sample rows from a table with optional limit and order.

pg_explain

Get query execution plan with optional analysis and format.

pg_stats

Get database or table statistics, with optional index usage.

pg_connections

List active connections with optional query details.

pg_locks

Show current locks with an option to show only blocked locks.

pg_analyze_query

AI-powered analysis of a given query with optional use of AI for synthesis.

pg_suggest_schema

AI-assisted suggestions to improve schema design for a given table.