Supports containerized deployments for both HTTP and stdio transports, enabling portable and isolated running environments.
Uses dotenv for environment variable management, allowing configuration of database credentials and server settings through .env files.
Built on Node.js, supporting both HTTP and stdio transports for interacting with PostgreSQL databases in different environments.
Supports containerized deployments using Podman as an alternative to Docker for running the MCP server.
Provides access to PostgreSQL databases, allowing users to list tables, retrieve schema information, and execute read-only SQL queries against PostgreSQL databases.
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:
Either environment variables
Or in the working directory (directory where
npx
command will be run): create a.env
file (the package usesdotenv
package)
Run using npx
Download node.js and npm from here
Run the package. By default, it will run streamable http on port 3000:
For stdio transport:
Environment Setup
Copy environment template
Edit your database credentials
Podman(or Docker) Usage
Install podman from here
Install
uv
from hereInstall podman compose package:
uv add podman-compose
(oruv sync
to sync packages inpyproject.toml
)
Test using Claude Desktop
First, install node.js and npm, build the project following the above instructions.
Edit your claude_desktop_config.json
Check if MCP Server has been enabled
Verify from Claude Desktop Window
Using MCP Server from Claude Desktop
Prompt: Show sales
table from last year.
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
Check Streamable HTTP MCP Server
First, run the server (shell where environment has been configured):
Run the mcp inspector from another terminal
After selecting Streamable HTTP
from drop down menu, insert http://localhost:3000/mcp
(default) into URL.
MCP tools:
MCP Resource:
Configuration
Environment Variables
You have to specify these inside the .env file.
Variable | Description | Default | Required |
| PostgreSQL username | - | Yes |
| PostgreSQL password | - | Yes |
| PostgreSQL host | - | Yes |
| PostgreSQL database name | - | Yes |
| HTTP server port | 3000 | No |
| HTTP server host | 0.0.0.0 | No |
| Allowed CORS origins (comma-separated) | localhost:8080,localhost:3000 | No |
| 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
Database Connection Errors
# Check your database credentials in .env # Ensure PostgreSQL is running and accessiblePort Already in Use
# Change PORT in .env or stop conflicting services lsof -i :3000Docker Build Issues
# Clean Docker cache npm run docker:clean docker system prune -aSession Management (HTTP)
# Sessions are stored in memory and will reset on server restart # For production, consider implementing persistent session storage
Development
Adding New Resources
Create a new file in
src/resources/
Implement the resource registration function
Add it to
src/server/server.ts
Adding New Tools
Create a new file in
src/tools/
Implement the tool registration function
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
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.
Related MCP Servers
- AsecurityAlicenseAqualityA 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 -181,751124AGPL 3.0
- -securityAlicense-qualityA Model Context Protocol server that enables interaction with PostgreSQL databases to list tables, retrieve schemas, and execute read-only SQL queries.Last updated -22MIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that enables interaction with PostgreSQL databases for analyzing setups, debugging issues, managing schemas, migrating data, and monitoring performance.Last updated -111MIT License
- -securityFlicense-qualityA 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 -