Skip to main content
Glama

PostgreSQL MCP Server

by ahmedmustahid
npmGitHub
TypeScript
35
20
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

MCP PostgreSQL Server (Stateful and Dual Transport)

A Model Context Protocol (MCP) server that provides both HTTP and Stdio transports for interacting with PostgreSQL databases. This server exposes database resources and tools through both transport methods, allowing for flexible integration in different environments.

Features

  • Dual Transport Support: Both HTTP (StreamableHTTPServerTransport) and Stdio (StdioServerTransport)

  • Database Resources: List tables and retrieve schema information

  • Query Tool: Execute read-only SQL queries

  • Stateful Sessions: HTTP transport supports session management

  • Docker Support: Containerized deployments for both transports

  • Production Ready: Graceful shutdown, error handling, and logging

Quick Start

Environment Setup

The database credentials must be passed as:

  1. Either environment variables

# PostgreSQL Database Connection String export POSTGRES_URL=your_connection_string # PostgreSQL Database Configuration if POSTGRES_URL is not provided export POSTGRES_USERNAME=your_username export POSTGRES_PASSWORD=your_password export POSTGRES_HOST=localhost export POSTGRES_PORT=5432 # this is the default export POSTGRES_DATABASE=your_database # HTTP Server Configuration # Following are the default values export PORT=3000 export HOST=0.0.0.0 # CORS Configuration (comma-separated list of allowed origins) # Following are the default values export CORS_ORIGIN=http://localhost:8080,http://localhost:3000 # Environment # Following are the default values export NODE_ENV=development

  1. Or in the working directory (directory where npx command will be run): create a .env file (the package uses dotenv package)

# .env.example # PostgreSQL Database Configuration POSTGRES_USERNAME=your_username POSTGRES_PASSWORD=your_password POSTGRES_HOST=localhost POSTGRES_DATABASE=your_database # HTTP Server Configuration PORT=3000 HOST=0.0.0.0 # CORS Configuration (comma-separated list of allowed origins) CORS_ORIGIN=http://localhost:8080,http://localhost:3000 # Environment NODE_ENV=development

Run using npx

  1. Download node.js and npm from here

  2. Run the package. By default, it will run streamable http on port 3000:

npx @ahmedmustahid/postgres-mcp-server # or npx @ahmedmustahid/postgres-mcp-server --port 3000 --verbose

  1. For stdio transport:

npx @ahmedmustahid/postgres-mcp-server stdio # npx @ahmedmustahid/postgres-mcp-server stdio --verbose

Environment Setup

Copy environment template

cp .env.example .env

Edit your database credentials

nano .env

Podman(or Docker) Usage

  1. Install podman from here

  2. Install uv from here

  3. Install podman compose package: uv add podman-compose (or uv sync to sync packages in pyproject.toml)

#get the environment variables set -a source .env set +a podman machine start make podman-up

Test using Claude Desktop

First, install node.js and npm, build the project following the above instructions. Edit your claude_desktop_config.json

{ "mcpServers": { "postgres-mcp-server": { "command": "npx", "args": [ "@ahmedmustahid/postgres-mcp-server", "stdio" ], "env": { "POSTGRES_USERNAME": "your-username", "POSTGRES_PASSWORD": "your-password", "POSTGRES_HOST": "hostname", "POSTGRES_DATABASE": "database-name" } } } }

Check if MCP Server has been enabled

Verify from Claude Desktop Window

Claude Desktop Window

Using MCP Server from Claude Desktop

Prompt: Show sales table from last year.

Result

Test using MCP Inspector

First, install node.js and npm, build the project following the above instructions. Install MCP Inspector: instructions: here

Check Stdio MCP Server

npx @modelcontextprotocol/inspector npx @ahmedmustahid/postgres-mcp-server stdio

Stdio in MCP Inspector

Check Streamable HTTP MCP Server

First, run the server (shell where environment has been configured):

npx @ahmedmustahid/postgres-mcp-server

Run the mcp inspector from another terminal

npx @modelcontextprotocol/inspector

After selecting Streamable HTTP from drop down menu, insert http://localhost:3000/mcp(default) into URL.

MCP tools: MCP Tools in MCP Inspector

MCP Resource: MCP Resource in MCP Inspector

Configuration

Environment Variables

You have to specify these inside the .env file.

Variable

Description

Default

Required

POSTGRES_USERNAME

PostgreSQL username

-

Yes

POSTGRES_PASSWORD

PostgreSQL password

-

Yes

POSTGRES_HOST

PostgreSQL host

-

Yes

POSTGRES_DATABASE

PostgreSQL database name

-

Yes

PORT

HTTP server port

3000

No

HOST

HTTP server host

0.0.0.0

No

CORS_ORIGIN

Allowed CORS origins (comma-separated)

localhost:8080,localhost:3000

No

NODE_ENV

Environment mode

development

No

Resources

Hello World (hello://world)

A simple greeting message for testing.

Database Tables (database://tables)

Lists all tables in the public schema with their schema URIs.

Database Schema (database://tables/{tableName}/schema)

Returns column information for a specific table.

Tools

query

Execute read-only SQL queries against the database.

Parameters:

  • sql (string): The SQL query to execute

Transport Differences

Feature

HTTP Transport

Stdio Transport

Session Management

✅ Stateful sessions

❌ Stateless

Concurrent Connections

✅ Multiple clients

❌ Single process

Web Integration

✅ REST API compatible

❌ CLI only

Interactive Use

✅ Via HTTP clients

✅ Direct stdio

Docker Deployment

✅ Web service

✅ CLI container

Health Checks

The HTTP server includes a basic health check endpoint accessible at the /health endpoint with a GET request (returns 405 Method Not Allowed, confirming the server is responsive).

Troubleshooting

Common Issues

  1. Database Connection Errors

    # Check your database credentials in .env # Ensure PostgreSQL is running and accessible

  2. Port Already in Use

    # Change PORT in .env or stop conflicting services lsof -i :3000

  3. Docker Build Issues

    # Clean Docker cache npm run docker:clean docker system prune -a

  4. Session Management (HTTP)

    # Sessions are stored in memory and will reset on server restart # For production, consider implementing persistent session storage

Development

Adding New Resources

  1. Create a new file in src/resources/

  2. Implement the resource registration function

  3. Add it to src/server/server.ts

Adding New Tools

  1. Create a new file in src/tools/

  2. Implement the tool registration function

  3. Add it to src/server/server.ts

License

MIT

Contributing

Please read the contributing guidelines and submit pull requests to the main repository.

This server cannot be installed

-
security - not tested
-
license - not tested
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A Model Context Protocol server providing dual transport (HTTP and Stdio) access to PostgreSQL databases, allowing AI assistants to query databases and fetch schema information through natural language.

  1. Features
    1. Quick Start
      1. Environment Setup
      2. Run using npx
      3. Environment Setup
    2. Podman(or Docker) Usage
      1. Test using Claude Desktop
        1. Check if MCP Server has been enabled
        2. Using MCP Server from Claude Desktop
        3. Test using MCP Inspector
      2. Configuration
        1. Environment Variables
      3. Resources
        1. Hello World (hello://world)
        2. Database Tables (database://tables)
        3. Database Schema (database://tables/{tableName}/schema)
      4. Tools
        1. query
      5. Transport Differences
        1. Health Checks
          1. Troubleshooting
            1. Common Issues
          2. Development
            1. Adding New Resources
            2. Adding New Tools
          3. License
            1. Contributing

              Related MCP Servers

              • PostgreSQL MCP Server

                HenkDz
                A
                security
                -
                license
                A
                quality
                A Model Context Protocol server that enables powerful PostgreSQL database management capabilities including analysis, schema management, data migration, and monitoring through natural language interactions.
                Last updated -
                18
                1,751
                126
                AGPL 3.0
                • Linux
                • Apple

              • PostgreSQL MCP Server

                hthuong09
                -
                security
                -
                license
                -
                quality
                A Model Context Protocol server that enables interaction with PostgreSQL databases to list tables, retrieve schemas, and execute read-only SQL queries.
                Last updated -
                22
                MIT License
                • Linux
                • Apple

              • PostgreSQL MCP Server

                1Levick3
                A
                security
                -
                license
                A
                quality
                A Model Context Protocol server that enables interaction with PostgreSQL databases for analyzing setups, debugging issues, managing schemas, migrating data, and monitoring performance.
                Last updated -
                1
                1
                1
                MIT License

              • Postgres MCP Server

                wongjingping
                -
                security
                -
                license
                -
                quality
                A Model Context Protocol server that enables querying PostgreSQL databases with tools for executing SELECT queries, inspecting database schemas, and listing tables through natural language.
                Last updated -

              View all related MCP servers

              New MCP Servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/ahmedmustahid/postgres-mcp-server'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server