povesma/postgres12-claude-mcp-server-usage

PostgreSQL 12 with MCP Server for AI Agents

Connect Claude Code to PostgreSQL 12 using the Model Context Protocol (MCP).

TL;DR

# Clone this repository
git clone https://github.com/povesma/postgres12-claude-mcp-server-usage
cd postgres12-claude-mcp-server-usage

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Start PostgreSQL 12
docker-compose up -d

# Verify it's running
docker exec postgres12 psql -U postgres -d mydb -c "SELECT version();"

# Pull MCP server image
docker pull crystaldba/postgres-mcp

# Start Claude Code in this directory
claude

In Claude Code, the MCP server will auto-connect. Ask Claude in natural language to interact with your database:

• "Show me all schemas in the database"
• "What tables are in the public schema?"
• "Run this SQL: SELECT version()"
• "Analyze the health of my database"

Claude will automatically use the appropriate MCP tools to fulfill your requests.

Step by Step

What's Included

This repository contains three configuration files:

1. docker-compose.yml - Defines PostgreSQL 12 container with database mydb, user/password postgres/postgres, exposed on port 5432
2. .mcp.json - MCP server configuration that runs crystaldba/postgres-mcp in Docker with unrestricted access
3. .claude/settings.json - Claude Code settings with enableAllProjectMcpServers: true and Docker command permissions (committable, applies to all users)

How It Works

Docker Compose Setup: The PostgreSQL 12 container creates an isolated Docker network called postgres12_default. This network allows other Docker containers to communicate with the database using the container name postgres12 as the hostname.

MCP Server Architecture: The Model Context Protocol (MCP) is a standardized way for AI agents to interact with external data sources. The crystaldba/postgres-mcp server acts as a bridge between Claude and PostgreSQL, exposing database operations as tools that Claude can call.

Network Configuration: When Claude Code launches the MCP server, it runs as a Docker container with --network postgres12_default, placing it on the same network as the database. The connection string uses postgres12:5432 (container name, not localhost) because Docker's DNS resolves container names within the same network.

Access Mode: The --access-mode=unrestricted flag allows full read/write access including CREATE, INSERT, UPDATE, DELETE operations. For production use, switch to --access-mode=restricted for read-only access.

Auto-Configuration: Claude Code reads .mcp.json in the project root to discover available MCP servers. The .claude/settings.json file with enableAllProjectMcpServers: true and pre-approved Docker commands automatically enables the postgres server for all users. Users can create .claude/settings.local.json to override settings locally (this file is gitignored).

Tool Invocation: Once connected, Claude can execute SQL queries, analyze database health, explain query plans, recommend indexes, and inspect schemas. The MCP server translates Claude's tool calls into PostgreSQL operations and returns results in a format Claude can understand and present to you.

Why Docker: Running the MCP server in Docker ensures consistent behavior across different environments and provides network isolation. The --rm flag in the configuration automatically removes the container after each use, preventing container buildup.

Database Credentials

• Host: localhost (from host machine) or postgres12 (from Docker network)
• Port: 5432
• Database: mydb
• User: postgres
• Password: postgres

Security Note: These are development credentials. For production, use environment variables or secrets management.