freakynit/postgres-mcp
3.2
If you are the rightful owner of postgres-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A lightweight Model Context Protocol (MCP) server designed to interact with a Postgres database, offering tools for SQL query execution, schema introspection, and natural language querying.
Postgres MCP
- A lightweight MCP (Model Context Protocol) server built to query Postgres database.
- It provides tools for
running raw SQL queries
,introspecting schema
, andquerying using plain English
. - You can use any OpenAI compatible LLM provider for English to SQL translation. This is fully automated, and you don't need to tell it anything.
Available Tools
Tool | Description |
---|---|
execute_raw_query | Run arbitrary SQL and return rows |
list_tables | List all non-system tables |
describe_table | Get column names, types, and nullability for a table |
execute_english_query | Translate natural language to SQL and optionally execute |
Minimum needed environment variables
POSTGRES_HOST
POSTGRES_USER
POSTGRES_PASSWORD
POSTGRES_DATABASE
LLM_API_KEY
: Needed only if you want English language query capabilityLLM_API_URL
: Needed only if you are using any other LLM provider other than OpenAI
Other environment variables
POSTGRES_PORT
LLM_MODEL
POSTGRES_SSL
(boolean)POSTGRES_VERIFY
(boolean)POSTGRES_SEND_RECEIVE_TIMEOUT
(in seconds)POSTGRES_CONNECT_TIMEOUT
(in seconds)
Configuring using mcpServers
json
For Mac and Linux
{
"mcpServers": {
"postgres-mcp": {
"command": "npx",
"args": ["-y", "@freakynit/postgres-mcp@latest"],
"env": {
"POSTGRES_HOST": "<POSTGRES HOST>",
"POSTGRES_USER": "<POSTGRES USER>",
"POSTGRES_PASSWORD": "<POSTGRES PASSWORD>",
"POSTGRES_DATABASE": "<POSTGRES DATABASE>",
"LLM_API_KEY": "<LLM API KEY if using english language queries>",
"LLM_API_URL": "<LLM API ENDPOINT if not using OpenAI>"
}
}
}
}
For Windows
{
"mcpServers": {
"postgres-mcp": {
"command": "cmd",
"args": ["/k", "npx", "-y", "@freakynit/postgres-mcp@latest"],
"env": {
"POSTGRES_HOST": "<POSTGRES HOST>",
"POSTGRES_USER": "<POSTGRES USER>",
"POSTGRES_PASSWORD": "<POSTGRES PASSWORD>",
"POSTGRES_DATABASE": "<POSTGRES DATABASE>",
"LLM_API_KEY": "<LLM API KEY if using english language queries>",
"LLM_API_URL": "<LLM API ENDPOINT if not using OpenAI>"
}
}
}
}
Development Docs
Prerequisites
- Node.js
- A PostgreSQL server
- An OpenAI (or any OpenAI compatible provider) API key and the endpoint (if not using OpenAI)
Installation
git clone https://github.com/freakynit/postgres-mcp.git
cd postgres-mcp
npm install
Configuration
Create a .env
file in the project root with the following variables:
# PostgreSQL
POSTGRES_HOST=your-db-host
POSTGRES_PORT=5432 # Optional, default 5432
POSTGRES_USER=your-username
POSTGRES_PASSWORD=your-password
POSTGRES_DATABASE=your-database
# SSL settings (optional)
POSTGRES_SSL=false # Or true
POSTGRES_VERIFY=false # Verify server cert if SSL true
# Timeouts (optional, seconds)
POSTGRES_SEND_RECEIVE_TIMEOUT=60
POSTGRES_CONNECT_TIMEOUT=60
# OpenAI
LLM_API_KEY=sk-... # Needed only if you want English language query capability
LLM_API_URL=https://api.openai.com/v1 # Optional, needed only if you are using any other LLM provider other than OpenAI
LLM_MODEL=gpt-4o # Optional, default gpt-4o
Usage
Start the server (Starts in stdio
mode):
node src/index.js
Project Structure
postgres-mcp/
āāā src/
ā āāā config.js # Environment parsing (Zod)
ā āāā db.js # Postgres client factory
ā āāā openai_client.js # OpenAI client factory
ā āāā register_tools.js # Tool registration orchestrator
ā āāā index.js # Entry point
ā āāā tools/ # Individual tool definitions
ā āāā execute_raw_query.js
ā āāā list_tables.js
ā āāā describe_table.js
ā āāā execute_english_query.js
āāā .env.example # Make sure to rename to `.env` and update it with correct values
āāā package.json
āāā README.md
Debugging with MCP inspector
npx @modelcontextprotocol/inspector node src/index.js
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/YourFeature
) - Commit your changes (
git commit -m "feat: ..."
) - Push to your branch (
git push origin feature/YourFeature
) - Open a Pull Request
License
This project is licensed under the MIT License. See for details.