postgres-mcp-server

An MCP (Model Context Protocol) server that lets Claude query and manipulate a PostgreSQL database using natural language.

Built with TypeScript, the official MCP SDK, and pg. Exposes a Streamable HTTP endpoint so it can be used remotely or locally with Claude Desktop / Claude Code.

✨ What it does

Once connected, you can ask Claude things like:

• "What tables do I have?"
• "Show me the last 10 rows from orders"
• "Insert a new user with email test@example.com"
• "Update order 42 to status shipped"
• "Delete all sessions where status = expired"

🛠️ Tools

| Tool | Description | |------|-------------| | list_tables | List all tables in the public schema | | describe_table | Show columns, types, nullability and defaults for a table | | select_rows | SELECT rows with optional WHERE clause and limit | | insert_row | INSERT a row, returns the inserted record | | update_rows | UPDATE rows matching a WHERE clause | | delete_rows | DELETE rows matching a WHERE clause |

🚀 Setup

1. Clone and install

git clone https://github.com/santisanti13/postgres-mcp-server.git
cd postgres-mcp-server
npm install

2. Configure your database

Set the DATABASE_URL environment variable to point to your Postgres instance:

export DATABASE_URL=postgresql://localhost/your_database

3. Build and run

npm run build
DATABASE_URL=postgresql://localhost/your_database npm start

The server starts at http://localhost:3000/mcp.

🔌 Connect to Claude

Claude Desktop / Claude Code

Add to your MCP config:

{
  "mcpServers": {
    "postgres": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Restart Claude and start asking questions about your database in plain language.

🧪 Test it manually

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

Should return the list of available tools.

⚠️ Notes

• This server gives Claude read and write access to your database. Use a dedicated database/user with restricted permissions for production use.
• update_rows and delete_rows accept raw SQL WHERE clauses — be careful when granting access to untrusted clients.

🏗️ Built with

• Model Context Protocol SDK
• node-postgres (pg)
• TypeScript + Express

Author

Built by Santi — SaaS builder, EdTech & GovTech.