cc-postgresql

A reliable, Windows-first PostgreSQL MCP server for Claude Code.

cc-postgresql lets Claude Code interact directly with PostgreSQL databases on your local Windows machine — without Docker, without bash assumptions, and without fragile tooling.

If you work primarily on Windows, use PowerShell, and want a PostgreSQL MCP server that stays connected and predictable, this is for you.

---

Why this exists

Many MCP database servers assume:

• macOS or Linux
• bash-first workflows
• Docker as a baseline dependency
• clean, opinionated environments

That works well — until it doesn't.

cc-postgresql exists for developers who:

• Work primarily on Windows
• Use PowerShell
• Prefer direct Node.js execution
• Want predictable behaviour
• Need tooling that remains stable in real-world dev environments
• Have very messy environments

If other tools work for you, that's great. This exists for when they don't.

---

What it does

cc-postgresql is a Model Context Protocol (MCP) server that exposes PostgreSQL access to Claude Code.

It provides Claude with structured tools to:

Tool	Purpose
onboarding	Teaches Claude safe and effective DB usage
list_tables	Lists all tables in a schema
get_table_schema	Returns complete schema information
execute_query	Executes arbitrary SQL

Everything runs locally, using your PostgreSQL credentials, under your control.

---

⚠️ Important: No safety rails

This server executes exactly the SQL it is given.

There are:

• No confirmation prompts
• No validation
• No undo
• No protection from destructive operations

If a query runs in PostgreSQL, it will run here.

Use a restricted database user. Do not point this at production unless you understand the risk.

This is deliberate.

---

Quick Start

Requirements

• Windows 10 / 11 (Mac/Linux should also work)
• Node.js 18+
• PostgreSQL 12+
• Claude Code

---

1. Clone and build

git clone https://github.com/howtobearealprogrammer/cc-postgresql-mcp.git
cd cc-postgresql\src
npm install
npm run build

The compiled server will be located at:

src\dist\index.js

---

2. Configure Claude Code MCP

Add the following to your MCP configuration file (.claude/mcp.json or local .mcp.json):

{
  "mcpServers": {
    "cc-postgresql": {
      "command": "node",
      "args": ["C:\\path\\to\\cc-postgresql\\src\\dist\\index.js"],
      "env": {
        "PGHOST": "localhost",
        "PGPORT": "5432",
        "PGUSER": "postgres",
        "PGPASSWORD": "your_password",
        "PGDATABASE": "your_database",
        "LOG_ENABLED": "false",
        "OTEL_ENABLED": "false"
      }
    }
  }
}

Mac/Linux paths: use forward slashes instead.

---

3. Verify installation

Restart Claude Code and ask:

Run the onboarding tool from cc-postgresql

If Claude responds with guidance about your database, you're connected.

---

Configuration Reference

Required

Variable	Description
PGHOST	PostgreSQL hostname
PGPORT	PostgreSQL port
PGUSER	Database user
PGPASSWORD	Database password

Optional

Variable	Description	Default
PGDATABASE	Default database	—
PG_CONNECTION_LIMIT	Pool size	10
PGSSLMODE	Set to "require" for SSL	—
LOG_ENABLED	Enable debug logging	false
LOG_PATH	Custom log path	auto
OTEL_ENABLED	Enable telemetry	false

---

OpenTelemetry (optional)

For production or long-running use, OpenTelemetry can be enabled:

{
  "OTEL_ENABLED": "true",
  "OTEL_ENDPOINT": "http://localhost:4318",
  "OTEL_SERVICE_NAME": "cc-postgresql"
}

Full OpenTelemetry options

Variable	Description	Default
OTEL_ENABLED	Enable telemetry	false
OTEL_ENDPOINT	Collector URL	—
OTEL_HOST	Collector hostname	localhost
OTEL_PORT	Collector port	4318
OTEL_PROTOCOL	http / https	http
OTEL_SERVICE_NAME	Trace service name	cc-postgresql

---

Multiple databases

You can configure multiple PostgreSQL connections by adding additional server entries:

{
  "mcpServers": {
    "postgresql-app": {
      "command": "node",
      "args": ["C:\\path\\to\\cc-postgresql\\src\\dist\\index.js"],
      "env": {
        "PGHOST": "localhost",
        "PGDATABASE": "app_db",
        "PGUSER": "app_user",
        "PGPASSWORD": "password",
        "PGPORT": "5432"
      }
    },
    "postgresql-analytics": {
      "command": "node",
      "args": ["C:\\path\\to\\cc-postgresql\\src\\dist\\index.js"],
      "env": {
        "PGHOST": "localhost",
        "PGDATABASE": "analytics_db",
        "PGUSER": "analytics_user",
        "PGPASSWORD": "password",
        "PGPORT": "5432"
      }
    }
  }
}

---

Troubleshooting

Enable logging to diagnose issues:

{
  "LOG_ENABLED": "true"
}

Logs are written to cc-postgresql-debug.log in the current directory, home directory, or temp folder.

Common issues

Access denied / authentication failed

• Check credentials
• Verify user permissions
• Check pg_hba.conf allows your connection method

Cannot find module

• Run npm run build in src
• Verify path points to src\dist\index.js

Claude can't see the server

• Check MCP JSON syntax
• Restart Claude Code completely

Connection refused

• Verify PostgreSQL is running
• Confirm host and port
• Check firewall settings

SSL required

• Set PGSSLMODE to require in your configuration

---

Running as a Windows service

Using NSSM

nssm install CCPostgreSQL "C:\Program Files\nodejs\node.exe"
nssm set CCPostgreSQL AppParameters "C:\path\to\cc-postgresql\src\dist\index.js"
nssm set CCPostgreSQL AppEnvironmentExtra PGHOST=localhost PGPORT=5432 PGUSER=postgres PGPASSWORD=password PGDATABASE=mydb
nssm start CCPostgreSQL

---

Development

cd src
npm install
npm run build
npm run watch
npm start

---

License

MIT

---

Built with Claude Code.
Not maintained at all.