hackerdogs/aws-postgres-mcp repository overview

⁠

⁠AWS Aurora PostgreSQL MCP Server

MCP server wrapper for AWS PostgreSQL MCP⁠ — connect to Amazon Aurora PostgreSQL or RDS PostgreSQL databases, inspect schemas, and run read-only SQL queries through natural language.

⁠What is AWS PostgreSQL MCP?

The AWS PostgreSQL MCP server (awslabs.postgres-mcp-server) acts as an intelligent bridge between an LLM and an Amazon Aurora PostgreSQL or RDS PostgreSQL instance. It introspects table schemas, translates natural-language questions into SQL, and returns query results — enabling conversational data exploration without writing SQL manually. See awslabs/mcp⁠ for full documentation.

AWS credentials required — set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION. A database connection string or endpoint must also be configured.

⁠Tools Reference

⁠Example Prompts

Here are example prompts you can use with Claude (or any MCP client) when this tool is connected:

• "List all tables in the 'public' schema and describe their columns."
• "How many orders were placed in the last 30 days? Query the orders table."
• "Show me the 10 most recent rows in the 'events' table."
• "What indexes exist on the 'users' table and are any columns missing indexes?"
• "Generate a SQL query that finds the top 5 customers by total spend in the last quarter."
• "Describe the foreign key relationships between the 'orders', 'customers', and 'products' tables."

⁠Deploy

⁠Docker Compose (recommended)

docker-compose up -d

⁠Docker Run (stdio mode)

docker run -i --rm \
  -e AWS_REGION \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  hackerdogs/aws-postgres-mcp:latest

⁠Docker Run (HTTP streamable mode)

docker run -d -p 8619:8619 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_PORT=8619 \
  -e AWS_REGION \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  hackerdogs/aws-postgres-mcp:latest

⁠MCP Client Configuration

⁠Stdio mode (default)

Add to your Claude Desktop or Cursor MCP config:

{
  "mcpServers": {
    "aws-postgres-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "MCP_TRANSPORT",
        "-e",
        "AWS_REGION",
        "-e",
        "AWS_ACCESS_KEY_ID",
        "-e",
        "AWS_SECRET_ACCESS_KEY",
        "hackerdogs/aws-postgres-mcp:latest"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "AWS_REGION": "",
        "AWS_ACCESS_KEY_ID": "",
        "AWS_SECRET_ACCESS_KEY": ""
      }
    }
  }
}

⁠HTTP mode (streamable-http)

First, start the server using Docker Compose or docker run with HTTP mode (see Deploy⁠ above), then point your MCP client at the running server:

{
  "mcpServers": {
    "aws-postgres-mcp": {
      "url": "http://localhost:8619/mcp"
    }
  }
}

⁠Environment Variables

⁠Installing in Hackerdogs

The fastest way to get started is through Hackerdogs⁠:

1. Log in to your Hackerdogs account.
2. Go to the Tools Catalog.
3. Search for the tool by name.
4. Expand the tool card and click Install — you're ready to go.

1. Vendor API key required? Add your key in the config environment variable field before clicking Install. Your key will be encrypted at rest.
2. Enable / Disable the tool anytime from the Enabled Tools page.
3. Need to update a key or parameter? Go to My Tools → toggle Show Decrypted Values → edit → Save.

⁠Build

docker build -t hackerdogs/aws-postgres-mcp:latest .

⁠Testing

⁠Automated tests

./test.sh

⁠Test directly with Docker

1. Start the server in HTTP mode:

docker run -d --rm --name aws-postgres-mcp-test -p 8619:8619 \
  -e MCP_TRANSPORT=streamable-http \
  -e AWS_REGION \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  hackerdogs/aws-postgres-mcp:latest

2. Initialize the MCP session:

SESSION_ID=$(curl -s -D - -X POST http://localhost:8619/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' \
  2>&1 | grep -i mcp-session-id | awk '{print $2}' | tr -d '\r\n')

curl -s -X POST http://localhost:8619/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

3. List available tools:

curl -s -X POST http://localhost:8619/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

4. Clean up:

docker stop aws-postgres-mcp-test