Skip to main content
Glama

PostgreSQL MCP Server

by ahmedmustahid
npmGitHub
TypeScript
170
2
OverviewInspectNewSchemaRelated 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 Configuration export POSTGRES_USERNAME=your_username export POSTGRES_PASSWORD=your_password export POSTGRES_HOST=localhost 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.

VariableDescriptionDefaultRequired
POSTGRES_USERNAMEPostgreSQL username-Yes
POSTGRES_PASSWORDPostgreSQL password-Yes
POSTGRES_HOSTPostgreSQL host-Yes
POSTGRES_DATABASEPostgreSQL database name-Yes
PORTHTTP server port3000No
HOSTHTTP server host0.0.0.0No
CORS_ORIGINAllowed CORS origins (comma-separated)localhost:8080,localhost:3000No
NODE_ENVEnvironment modedevelopmentNo

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

FeatureHTTP TransportStdio 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
F
license - not found
-
quality - not tested

How are these scores calculated?

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
                -
                security
                A
                license
                -
                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 -
                355
                46
                TypeScript
                AGPL 3.0
                • Linux
                • Apple

              • PostgreSQL MCP Server

                hthuong09
                -
                security
                F
                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 -
                16,948
                JavaScript
                • Linux
                • Apple

              • PostgreSQL MCP Server

                1Levick3
                -
                security
                A
                license
                -
                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 -
                6
                TypeScript
                MIT License

              • MCP SQL Server

                ryudg
                -
                security
                A
                license
                -
                quality
                A Model Context Protocol server that provides AI assistants with comprehensive access to SQL databases, enabling schema inspection, query execution, and database operations with enterprise-grade security.
                Last updated -
                54
                TypeScript
                MIT License

              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