# PostgreSQL MCP Server
A secure, read-only PostgreSQL Model Context Protocol (MCP) server for AI
assistant integration with automatic database discovery and connection management.
## What It Does
This tool provides two main components:
- **Query Executor** (`execute_query.py`): Interactive PostgreSQL query
execution with support for direct queries, file input, and interactive mode
- **MCP Server** (`mcp_postgresql_server.py`): AI assistant integration that allows
natural language database interactions through Claude and other MCP clients
## Key Features
- **Automatic Database Discovery**: Scans project files for database
configurations and presents options for selection
- **Read-Only Safety**: Blocks write operations by default (configurable)
- **Interactive Configuration**: Guides users through database setup
with automatic `.env` file management
- **Connection Pooling**: Efficient PostgreSQL connection management
- **AI Integration**: Works seamlessly with Claude Desktop and Cursor IDE
## Quick Start
**Prerequisites**: Ensure you have [uv](https://docs.astral.sh/uv/) installed.
### Using uvx (Recommended)
Run directly without installation:
```bash
# MCP Server for AI integration
uvx mcp-postgresql-server
# Query executor
uvx --from mcp-postgresql-server execute-query "SELECT version()"
```
### Configuration
Set your database connection:
```bash
export MCP_POSTGRESQL_DATABASE="postgres://username:password@hostname:port/database"
```
Or create a `.env` file:
```env
MCP_POSTGRESQL_DATABASE=postgres://username:password@hostname:port/database
MCP_POSTGRESQL_READ_ONLY=true
MCP_POSTGRESQL_LOG_FILE=./mcp-postgresql.log
MCP_POSTGRESQL_LOG_LEVEL=info
```
## Usage Examples
### Query Executor
**Using uvx (recommended):**
```bash
# Interactive mode
uvx --from mcp-postgresql-server execute-query
# Direct query
uvx --from mcp-postgresql-server execute-query "SELECT COUNT(*) FROM users"
# From file
uvx --from mcp-postgresql-server execute-query --file queries.sql
```
**Using Python directly:**
```bash
# Interactive mode
python3 execute_query.py
# Direct query
python3 execute_query.py "SELECT COUNT(*) FROM users"
# From file
python3 execute_query.py --file queries.sql
```
### MCP Server with Claude Code (globally)
Add to `~/.claude.json`:
```json
{
"mcpServers": {
"mcp-postgres": {
"command": "uvx",
"args": ["mcp-postgresql-server"],
"env": {
"MCP_POSTGRESQL_CWD": "${PWD}"
}
}
}
}
```
Then ask Claude:
- "Show me all tables in the database"
- "Execute SELECT COUNT(*) FROM users"
- "Help me write a query to find recent orders"
### Cursor IDE Integration
Create/update `mcp.json` in your project root:
```json
{
"mcpServers": {
"mcp-postgresql-server": {
"command": "uvx",
"args": ["mcp-postgresql-server"],
"env": {
"MCP_POSTGRESQL_CWD": "."
}
}
}
}
```
## Configuration Discovery
The server automatically discovers database configurations from:
- `.env` files
- `.conf` and `.ini` files
- `.json` and `.yaml` files
- Individual parameter files (db.host, db.user, etc.)
When multiple configurations are found, it presents an interactive selection menu.
Saved configurations are stored in a `.env` file for future use
using MCP_POSTGRESQL_DATABASE variable.
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_POSTGRESQL_DATABASE` | PostgreSQL connection URI | Required |
| `MCP_POSTGRESQL_READ_ONLY` | Enable read-only mode | `true` |
| `MCP_POSTGRESQL_LOG_FILE` | Log file path (optional) | None |
| `MCP_POSTGRESQL_LOG_LEVEL` | Log level (debug, info, warning, error, critical) | `error` |
| `MCP_POSTGRESQL_CWD` | Path of the project working directory | `.` |
## Security
- **Read-only by default**: Blocks INSERT, UPDATE, CREATE, ALTER, DROP operations
- **Connection validation**: Validates all database connections before use
- **Credential protection**: Supports environment variables and `.env` files
- **Error handling**: Comprehensive error reporting without exposing sensitive data
## Common Issues
**Connection errors**: Verify `MCP_POSTGRESQL_DATABASE` format: `postgres://user:password@host:port/database`
**Permission issues**: Ensure database user has appropriate SELECT permissions
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-postgresql-server",
"maintainer": "sebcbi1",
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "mcp, postgresql, database, ai-assistant, claude, model-context-protocol, sql, postgres, database-tools",
"author": "sebcbi1",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/2c/af/1bdbea1bf0edfb675dd786eab7a40665581ad935f5c0b39e1e8b8da5f8c7/mcp_postgresql_server-1.4.0.tar.gz",
"platform": null,
"description": "# PostgreSQL MCP Server\n\nA secure, read-only PostgreSQL Model Context Protocol (MCP) server for AI\nassistant integration with automatic database discovery and connection management.\n\n## What It Does\n\nThis tool provides two main components:\n\n- **Query Executor** (`execute_query.py`): Interactive PostgreSQL query\nexecution with support for direct queries, file input, and interactive mode\n- **MCP Server** (`mcp_postgresql_server.py`): AI assistant integration that allows\nnatural language database interactions through Claude and other MCP clients\n\n## Key Features\n\n- **Automatic Database Discovery**: Scans project files for database\nconfigurations and presents options for selection\n- **Read-Only Safety**: Blocks write operations by default (configurable)\n- **Interactive Configuration**: Guides users through database setup\nwith automatic `.env` file management\n- **Connection Pooling**: Efficient PostgreSQL connection management\n- **AI Integration**: Works seamlessly with Claude Desktop and Cursor IDE\n\n## Quick Start\n\n**Prerequisites**: Ensure you have [uv](https://docs.astral.sh/uv/) installed.\n\n### Using uvx (Recommended)\n\nRun directly without installation:\n\n```bash\n# MCP Server for AI integration\nuvx mcp-postgresql-server\n\n# Query executor\nuvx --from mcp-postgresql-server execute-query \"SELECT version()\"\n```\n\n### Configuration\n\nSet your database connection:\n\n```bash\nexport MCP_POSTGRESQL_DATABASE=\"postgres://username:password@hostname:port/database\"\n```\n\nOr create a `.env` file:\n\n```env\nMCP_POSTGRESQL_DATABASE=postgres://username:password@hostname:port/database\nMCP_POSTGRESQL_READ_ONLY=true\nMCP_POSTGRESQL_LOG_FILE=./mcp-postgresql.log\nMCP_POSTGRESQL_LOG_LEVEL=info\n```\n\n## Usage Examples\n\n### Query Executor\n\n**Using uvx (recommended):**\n\n```bash\n# Interactive mode\nuvx --from mcp-postgresql-server execute-query\n\n# Direct query\nuvx --from mcp-postgresql-server execute-query \"SELECT COUNT(*) FROM users\"\n\n# From file\nuvx --from mcp-postgresql-server execute-query --file queries.sql\n```\n\n**Using Python directly:**\n\n```bash\n# Interactive mode\npython3 execute_query.py\n\n# Direct query\npython3 execute_query.py \"SELECT COUNT(*) FROM users\"\n\n# From file\npython3 execute_query.py --file queries.sql\n```\n\n### MCP Server with Claude Code (globally)\n\nAdd to `~/.claude.json`:\n\n```json\n{\n \"mcpServers\": {\n \"mcp-postgres\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-postgresql-server\"],\n \"env\": {\n \"MCP_POSTGRESQL_CWD\": \"${PWD}\"\n }\n }\n }\n}\n```\n\nThen ask Claude:\n\n- \"Show me all tables in the database\"\n- \"Execute SELECT COUNT(*) FROM users\"\n- \"Help me write a query to find recent orders\"\n\n### Cursor IDE Integration\n\nCreate/update `mcp.json` in your project root:\n\n```json\n{\n \"mcpServers\": {\n \"mcp-postgresql-server\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-postgresql-server\"],\n \"env\": {\n \"MCP_POSTGRESQL_CWD\": \".\"\n }\n }\n }\n}\n```\n\n## Configuration Discovery\n\nThe server automatically discovers database configurations from:\n\n- `.env` files\n- `.conf` and `.ini` files\n- `.json` and `.yaml` files\n- Individual parameter files (db.host, db.user, etc.)\n\nWhen multiple configurations are found, it presents an interactive selection menu.\nSaved configurations are stored in a `.env` file for future use\nusing MCP_POSTGRESQL_DATABASE variable.\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `MCP_POSTGRESQL_DATABASE` | PostgreSQL connection URI | Required |\n| `MCP_POSTGRESQL_READ_ONLY` | Enable read-only mode | `true` |\n| `MCP_POSTGRESQL_LOG_FILE` | Log file path (optional) | None |\n| `MCP_POSTGRESQL_LOG_LEVEL` | Log level (debug, info, warning, error, critical) | `error` |\n| `MCP_POSTGRESQL_CWD` | Path of the project working directory | `.` |\n\n## Security\n\n- **Read-only by default**: Blocks INSERT, UPDATE, CREATE, ALTER, DROP operations\n- **Connection validation**: Validates all database connections before use\n- **Credential protection**: Supports environment variables and `.env` files\n- **Error handling**: Comprehensive error reporting without exposing sensitive data\n\n## Common Issues\n\n**Connection errors**: Verify `MCP_POSTGRESQL_DATABASE` format: `postgres://user:password@host:port/database`\n\n**Permission issues**: Ensure database user has appropriate SELECT permissions\n",
"bugtrack_url": null,
"license": null,
"summary": "A secure, read-only PostgreSQL Model Context Protocol (MCP) server for AI assistant integration with automatic database discovery and connection management",
"version": "1.4.0",
"project_urls": {
"Documentation": "https://github.com/sebcbi1/mcp-postgresql-server/blob/main/README.md",
"Homepage": "https://github.com/sebcbi1/mcp-postgresql-server",
"Issues": "https://github.com/sebcbi1/mcp-postgresql-server/issues",
"Repository": "https://github.com/sebcbi1/mcp-postgresql-server"
},
"split_keywords": [
"mcp",
" postgresql",
" database",
" ai-assistant",
" claude",
" model-context-protocol",
" sql",
" postgres",
" database-tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ec786617eb88d0ccf80b9fcd99211080b1d40d9c42cadaf79926adccf8a463db",
"md5": "e16cd8bd2d4d02f40efc74f6420aa870",
"sha256": "2a06863d98006be77d1c2475a5fe253cd07043c7c3e578cae0a924d175ed4d01"
},
"downloads": -1,
"filename": "mcp_postgresql_server-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e16cd8bd2d4d02f40efc74f6420aa870",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 22465,
"upload_time": "2025-09-05T11:32:30",
"upload_time_iso_8601": "2025-09-05T11:32:30.715425Z",
"url": "https://files.pythonhosted.org/packages/ec/78/6617eb88d0ccf80b9fcd99211080b1d40d9c42cadaf79926adccf8a463db/mcp_postgresql_server-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2caf1bdbea1bf0edfb675dd786eab7a40665581ad935f5c0b39e1e8b8da5f8c7",
"md5": "80d50dba71f3aa09f59eb801cac815ca",
"sha256": "47057faa940e7848b87d697ab31ab993c5cca69c8ef1332f7e6f73dff79e0e4d"
},
"downloads": -1,
"filename": "mcp_postgresql_server-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "80d50dba71f3aa09f59eb801cac815ca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 21543,
"upload_time": "2025-09-05T11:32:31",
"upload_time_iso_8601": "2025-09-05T11:32:31.709318Z",
"url": "https://files.pythonhosted.org/packages/2c/af/1bdbea1bf0edfb675dd786eab7a40665581ad935f5c0b39e1e8b8da5f8c7/mcp_postgresql_server-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-05 11:32:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sebcbi1",
"github_project": "mcp-postgresql-server",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mcp-postgresql-server"
}
JSON
