<div align="center">
<img src="https://raw.githubusercontent.com/andre-c-andersen/pg-mcp/refs/heads/master/assets/postgres-mcp-lite.png" alt="Postgres MCP Lite Logo" width="600"/>
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/pg-mcp/)
[](https://x.com/AndreCAndersen)
[](https://github.com/andre-c-andersen/pg-mcp/graphs/contributors)
<h3>A lightweight, read-only-by-default Postgres MCP server for data analysts and ETL developers.</h3>
</div>
## Overview
**Postgres MCP Lite** is a lightweight, open-source Model Context Protocol (MCP) server for PostgreSQL, designed specifically for **data analysts and ETL developers** who need to explore and understand database schemas and data.
This is a streamlined fork of [postgres-mcp](https://github.com/crystaldba/postgres-mcp) by [Crystal DBA](https://www.linkedin.com/company/crystaldba/), focused on **safe data exploration** rather than database administration:
- **🔍 Data Exploration** - Understand database schemas, table structures, and relationships with AI assistance
- **📊 Query Analysis** - Generate and execute SQL queries to analyze data patterns and relationships
- **🛡️ Read-Only by Default** - Defaults to restricted mode with SQL validation, preventing accidental modifications
- **🔌 Multiple [Transports](https://modelcontextprotocol.io/docs/concepts/transports)** - Supports both stdio and SSE
- **🌐 Multi-Database Support** - Connect to multiple databases simultaneously (app, ETL, analytics, etc.)
**Perfect for:**
- 📈 Data analysts exploring production databases safely
- 🔄 ETL developers understanding source and target schemas
- 🤖 AI-assisted data discovery and documentation
- 📝 Generating data analysis queries with LLM help
## Quick Start
### Prerequisites
Before getting started, ensure you have:
1. Access credentials for your database.
2. Python 3.12 or higher.
#### Access Credentials
You can confirm your access credentials are valid by using `psql` or a GUI tool such as [pgAdmin](https://www.pgadmin.org/).
### Installation
If you have `pipx` installed you can install Postgres MCP Lite with:
```bash
pipx install pg-mcp
```
Otherwise, install Postgres MCP Lite with `uv`:
```bash
uv pip install pg-mcp
```
If you need to install `uv`, see the [uv installation instructions](https://docs.astral.sh/uv/getting-started/installation/).
### Configure Your AI Assistant
We provide full instructions for configuring Postgres MCP Lite with Claude Desktop.
Many MCP clients have similar configuration files, you can adapt these steps to work with the client of your choice.
#### Claude Desktop Configuration
You will need to edit the Claude Desktop configuration file to add Postgres MCP Lite.
The location of this file depends on your operating system:
- MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%/Claude/claude_desktop_config.json`
You can also use `Settings` menu item in Claude Desktop to locate the configuration file.
You will now edit the `mcpServers` section of the configuration file.
##### If you are using `pipx`
```json
{
"mcpServers": {
"postgres": {
"command": "pg-mcp",
"env": {
"DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
}
}
}
}
```
##### If you are using `uv`
```json
{
"mcpServers": {
"postgres": {
"command": "uv",
"args": [
"run",
"pg-mcp",
"--access-mode=unrestricted"
],
"env": {
"DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
}
}
}
}
```
##### Connection URI
Replace `postgresql://...` with your [Postgres database connection URI](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS).
##### Multiple Database Connections
Postgres MCP Lite supports connecting to multiple databases simultaneously. This is useful when you need to work across different databases (e.g., application database, ETL database, analytics database).
To configure multiple connections, define additional environment variables with the pattern `DATABASE_URI_<NAME>`:
```json
{
"mcpServers": {
"postgres": {
"command": "pg-mcp",
"env": {
"DATABASE_URI_APP": "postgresql://user:pass@localhost:5432/app_db",
"DATABASE_URI_ETL": "postgresql://user:pass@localhost:5432/etl_db",
"DATABASE_URI_ANALYTICS": "postgresql://user:pass@localhost:5432/analytics_db",
"DATABASE_DESC_APP": "Main application database with user data and transactions",
"DATABASE_DESC_ETL": "ETL staging database for data processing pipelines",
"DATABASE_DESC_ANALYTICS": "Read-only analytics database with aggregated metrics"
}
}
}
}
```
Each connection is identified by its name (the part after `DATABASE_URI_`, converted to lowercase):
- `DATABASE_URI_APP` → connection name: `"app"`
- `DATABASE_URI_ETL` → connection name: `"etl"`
- `DATABASE_URI_ANALYTICS` → connection name: `"analytics"`
**Connection Descriptions**: You can optionally provide descriptions for each connection using `DATABASE_DESC_<NAME>` environment variables. These descriptions help the AI assistant understand which database to use for different tasks. The descriptions are:
- Automatically displayed in the server context (visible to the AI without requiring a tool call)
- Useful for guiding the AI to select the appropriate database
When using tools, the LLM will specify which connection to use via the `conn_name` parameter:
- `list_schemas(conn_name="app")` - Lists schemas in the app database
- `explain_query(conn_name="etl", sql="SELECT ...")` - Explains query in the ETL database
For backward compatibility, `DATABASE_URI` (without a suffix) maps to the connection name `"default"`.
##### Access Mode
**Restricted mode (read-only) is the default.** You can query and explore schemas safely—writes and DDL are blocked.
**Allowed:** SELECT, EXPLAIN, SHOW, ANALYZE, schema introspection
**Blocked:** INSERT, UPDATE, DELETE, CREATE, ALTER, DROP
**💡 Best Practice:** Use database credentials with read-only permissions. Software makes mistakes—limit what an AI agent can access, just like you would for any automated process.
**⚠️ Data Privacy:** Database content will be sent to your LLM provider. Only connect to databases containing data you have the right to share. Consider data protection regulations (GDPR, HIPAA, etc.) and your organization's policies before use.
**⚠️ Unrestricted Mode (Dangerous)**
Only connect to databases you're willing to destroy. Allows full write access and DDL. Add `--access-mode=unrestricted` to the args array as shown in the `uv` example above.
##### Logging Configuration
When using stdio transport (the default), Postgres MCP Lite writes logs to stderr to avoid interfering with the MCP protocol (which uses stdout). When using SSE transport, logs go to stdout.
You can control the logging verbosity using the `LOG_LEVEL` environment variable:
- `DEBUG` - Show all logs including debug messages
- `INFO` - Show info, warning, and error messages (default)
- `WARNING` - Show only warnings and errors
- `ERROR` - Show only errors
- `CRITICAL` - Show only critical errors
- `NONE` - Disable all logging
Example configuration with logging disabled:
```json
{
"mcpServers": {
"postgres": {
"command": "pg-mcp",
"env": {
"DATABASE_URI": "postgresql://username:password@localhost:5432/dbname",
"LOG_LEVEL": "NONE"
}
}
}
}
```
#### Claude Code Configuration
[Claude Code](https://docs.claude.com/en/docs/claude-code/overview) is Anthropic's agentic coding tool for your terminal. To configure Postgres MCP Lite with Claude Code:
1. **Install Claude Code** (if you haven't already):
```bash
npm install -g @anthropic-ai/claude-code
```
2. **Edit your Claude Code configuration file**:
- Location: `~/.claude.json` (Linux/macOS) or `%USERPROFILE%\.claude.json` (Windows)
- Or use the CLI wizard: `claude mcp add`
3. **Add Postgres MCP Lite to your configuration**:
```json
{
"mcpServers": {
"postgres": {
"command": "pg-mcp",
"env": {
"DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
}
}
}
}
```
4. **Restart Claude Code** for changes to take effect. Verify with:
```bash
claude mcp list
```
#### Other MCP Clients
Many MCP clients have similar configuration files to Claude Desktop, and you can adapt the examples above to work with the client of your choice.
- If you are using Cursor, you can use navigate from the `Command Palette` to `Cursor Settings`, then open the `MCP` tab to access the configuration file.
- If you are using Windsurf, you can navigate to from the `Command Palette` to `Open Windsurf Settings Page` to access the configuration file.
- If you are using Goose run `goose configure`, then select `Add Extension`.
## SSE Transport
Postgres MCP Lite supports the [SSE transport](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse), which allows multiple MCP clients to share one server, possibly a remote server.
To use the SSE transport, you need to start the server with the `--transport=sse` option.
For example, run:
```bash
DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
pg-mcp --transport=sse
```
Then update your MCP client configuration to call the MCP server.
For example, in Cursor's `mcp.json` or Cline's `cline_mcp_settings.json` you can put:
```json
{
"mcpServers": {
"postgres": {
"type": "sse",
"url": "http://localhost:8000/sse"
}
}
}
```
For Windsurf, the format in `mcp_config.json` is slightly different:
```json
{
"mcpServers": {
"postgres": {
"type": "sse",
"serverUrl": "http://localhost:8000/sse"
}
}
}
```
## Usage Examples
### Explore Database Schema
Ask:
> Show me all the tables in the database and their structure.
### Generate SQL Queries
Ask:
> Write a query to find all orders from the past month with their customer details.
### Analyze Table Structure
Ask:
> What indexes exist on the orders table and what columns do they cover?
### Execute Data Queries
Ask:
> Show me the top 10 customers by order count in 2024.
## MCP Server API
The [MCP standard](https://modelcontextprotocol.io/) defines various types of endpoints: Tools, Resources, Prompts, and others.
Postgres MCP Lite provides functionality via [MCP tools](https://modelcontextprotocol.io/docs/concepts/tools) alone.
We chose this approach because the [MCP client ecosystem](https://modelcontextprotocol.io/clients) has widespread support for MCP tools.
This contrasts with the approach of other Postgres MCP servers, including the [Reference Postgres MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres), which use [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) to expose schema information.
Postgres MCP Lite provides 4 essential tools:
| Tool Name | Description |
|-----------|-------------|
| `list_schemas` | Lists all database schemas available in the PostgreSQL instance. |
| `list_objects` | Lists database objects (tables, views, sequences, extensions) within a specified schema. |
| `get_object_details` | Provides detailed information about a specific database object, including columns, constraints, and indexes. |
| `execute_sql` | Executes SQL statements on the database, with read-only limitations when connected in restricted mode. |
## Related Projects
**Other Postgres MCP Servers**
- [Reference PostgreSQL MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres) - Official reference implementation
- [PG-MCP](https://github.com/stuzero/pg-mcp-server) - Feature-rich PostgreSQL MCP server
- [Supabase Postgres MCP Server](https://github.com/supabase-community/supabase-mcp) - Supabase integration
- [Query MCP](https://github.com/alexander-zuev/supabase-mcp-server) - Three-tier safety architecture
## Technical Notes
### Postgres Client Library
Postgres MCP Lite uses [psycopg3](https://www.psycopg.org/) in **synchronous mode** for reliable database connectivity. It leverages [libpq](https://www.postgresql.org/docs/current/libpq.html) for full Postgres feature support.
### Safe SQL Execution by Default
Postgres MCP Lite **defaults to restricted mode** for safe data exploration:
- **Restricted Mode (Default)**: Read-only transactions with SQL validation and execution time limits. Perfect for production databases.
- **Unrestricted Mode**: Full read/write access for development or when explicitly needed.
In restricted mode, SQL is parsed using [pglast](https://pglast.readthedocs.io/) to validate that only safe, read-only operations are allowed (SELECT, EXPLAIN, SHOW, ANALYZE, VACUUM). All queries execute within read-only transactions and are automatically rolled back, preventing accidental data modifications.
### Schema Information
Schema tools provide AI agents with the information needed to generate correct SQL. While LLMs can query Postgres system catalogs directly, dedicated tools ensure consistent, reliable schema exploration across different LLM capabilities.
## Postgres MCP Lite Development
The instructions below are for developers who want to work on Postgres MCP Lite, or users who prefer to install Postgres MCP Lite from source.
### Local Development Setup
1. **Install uv**:
```bash
curl -sSL https://astral.sh/uv/install.sh | sh
```
2. **Clone the repository**:
```bash
git clone https://github.com/andre-c-andersen/pg-mcp.git
cd pg-mcp
```
3. **Install dependencies**:
```bash
uv pip install -e .
uv sync
```
4. **Run the server**:
```bash
uv run pg-mcp "postgres://user:password@localhost:5432/dbname"
```
Raw data
{
"_id": null,
"home_page": null,
"name": "pg-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "ai, database, llm, mcp, model-context-protocol, postgres, postgresql",
"author": null,
"author_email": "\"Andr\u00e9 C. Andersen\" <andre@andersen.im>",
"download_url": "https://files.pythonhosted.org/packages/cb/0f/bf22e30d1657baa9423974605b052ed71ae6f3feea826583d4105d81a1f0/pg_mcp-0.2.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n<img src=\"https://raw.githubusercontent.com/andre-c-andersen/pg-mcp/refs/heads/master/assets/postgres-mcp-lite.png\" alt=\"Postgres MCP Lite Logo\" width=\"600\"/>\n\n[](https://opensource.org/licenses/MIT)\n[](https://pypi.org/project/pg-mcp/)\n[](https://x.com/AndreCAndersen)\n[](https://github.com/andre-c-andersen/pg-mcp/graphs/contributors)\n\n<h3>A lightweight, read-only-by-default Postgres MCP server for data analysts and ETL developers.</h3>\n\n</div>\n\n## Overview\n\n**Postgres MCP Lite** is a lightweight, open-source Model Context Protocol (MCP) server for PostgreSQL, designed specifically for **data analysts and ETL developers** who need to explore and understand database schemas and data.\n\nThis is a streamlined fork of [postgres-mcp](https://github.com/crystaldba/postgres-mcp) by [Crystal DBA](https://www.linkedin.com/company/crystaldba/), focused on **safe data exploration** rather than database administration:\n\n- **\ud83d\udd0d Data Exploration** - Understand database schemas, table structures, and relationships with AI assistance\n- **\ud83d\udcca Query Analysis** - Generate and execute SQL queries to analyze data patterns and relationships\n- **\ud83d\udee1\ufe0f Read-Only by Default** - Defaults to restricted mode with SQL validation, preventing accidental modifications\n- **\ud83d\udd0c Multiple [Transports](https://modelcontextprotocol.io/docs/concepts/transports)** - Supports both stdio and SSE\n- **\ud83c\udf10 Multi-Database Support** - Connect to multiple databases simultaneously (app, ETL, analytics, etc.)\n\n**Perfect for:**\n- \ud83d\udcc8 Data analysts exploring production databases safely\n- \ud83d\udd04 ETL developers understanding source and target schemas\n- \ud83e\udd16 AI-assisted data discovery and documentation\n- \ud83d\udcdd Generating data analysis queries with LLM help\n\n## Quick Start\n\n### Prerequisites\n\nBefore getting started, ensure you have:\n1. Access credentials for your database.\n2. Python 3.12 or higher.\n\n#### Access Credentials\n You can confirm your access credentials are valid by using `psql` or a GUI tool such as [pgAdmin](https://www.pgadmin.org/).\n\n\n### Installation\n\nIf you have `pipx` installed you can install Postgres MCP Lite with:\n\n```bash\npipx install pg-mcp\n```\n\nOtherwise, install Postgres MCP Lite with `uv`:\n\n```bash\nuv pip install pg-mcp\n```\n\nIf you need to install `uv`, see the [uv installation instructions](https://docs.astral.sh/uv/getting-started/installation/).\n\n\n### Configure Your AI Assistant\n\nWe provide full instructions for configuring Postgres MCP Lite with Claude Desktop.\nMany MCP clients have similar configuration files, you can adapt these steps to work with the client of your choice.\n\n#### Claude Desktop Configuration\n\nYou will need to edit the Claude Desktop configuration file to add Postgres MCP Lite.\nThe location of this file depends on your operating system:\n- MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%/Claude/claude_desktop_config.json`\n\nYou can also use `Settings` menu item in Claude Desktop to locate the configuration file.\n\nYou will now edit the `mcpServers` section of the configuration file.\n\n##### If you are using `pipx`\n\n```json\n{\n \"mcpServers\": {\n \"postgres\": {\n \"command\": \"pg-mcp\",\n \"env\": {\n \"DATABASE_URI\": \"postgresql://username:password@localhost:5432/dbname\"\n }\n }\n }\n}\n```\n\n\n##### If you are using `uv`\n\n```json\n{\n \"mcpServers\": {\n \"postgres\": {\n \"command\": \"uv\",\n \"args\": [\n \"run\",\n \"pg-mcp\",\n \"--access-mode=unrestricted\"\n ],\n \"env\": {\n \"DATABASE_URI\": \"postgresql://username:password@localhost:5432/dbname\"\n }\n }\n }\n}\n```\n\n\n##### Connection URI\n\nReplace `postgresql://...` with your [Postgres database connection URI](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS).\n\n\n##### Multiple Database Connections\n\nPostgres MCP Lite supports connecting to multiple databases simultaneously. This is useful when you need to work across different databases (e.g., application database, ETL database, analytics database).\n\nTo configure multiple connections, define additional environment variables with the pattern `DATABASE_URI_<NAME>`:\n\n```json\n{\n \"mcpServers\": {\n \"postgres\": {\n \"command\": \"pg-mcp\",\n \"env\": {\n \"DATABASE_URI_APP\": \"postgresql://user:pass@localhost:5432/app_db\",\n \"DATABASE_URI_ETL\": \"postgresql://user:pass@localhost:5432/etl_db\",\n \"DATABASE_URI_ANALYTICS\": \"postgresql://user:pass@localhost:5432/analytics_db\",\n \"DATABASE_DESC_APP\": \"Main application database with user data and transactions\",\n \"DATABASE_DESC_ETL\": \"ETL staging database for data processing pipelines\",\n \"DATABASE_DESC_ANALYTICS\": \"Read-only analytics database with aggregated metrics\"\n }\n }\n }\n}\n```\n\nEach connection is identified by its name (the part after `DATABASE_URI_`, converted to lowercase):\n- `DATABASE_URI_APP` \u2192 connection name: `\"app\"`\n- `DATABASE_URI_ETL` \u2192 connection name: `\"etl\"`\n- `DATABASE_URI_ANALYTICS` \u2192 connection name: `\"analytics\"`\n\n**Connection Descriptions**: You can optionally provide descriptions for each connection using `DATABASE_DESC_<NAME>` environment variables. These descriptions help the AI assistant understand which database to use for different tasks. The descriptions are:\n- Automatically displayed in the server context (visible to the AI without requiring a tool call)\n- Useful for guiding the AI to select the appropriate database\n\nWhen using tools, the LLM will specify which connection to use via the `conn_name` parameter:\n- `list_schemas(conn_name=\"app\")` - Lists schemas in the app database\n- `explain_query(conn_name=\"etl\", sql=\"SELECT ...\")` - Explains query in the ETL database\n\nFor backward compatibility, `DATABASE_URI` (without a suffix) maps to the connection name `\"default\"`.\n\n\n##### Access Mode\n\n**Restricted mode (read-only) is the default.** You can query and explore schemas safely\u2014writes and DDL are blocked.\n\n**Allowed:** SELECT, EXPLAIN, SHOW, ANALYZE, schema introspection\n**Blocked:** INSERT, UPDATE, DELETE, CREATE, ALTER, DROP\n\n**\ud83d\udca1 Best Practice:** Use database credentials with read-only permissions. Software makes mistakes\u2014limit what an AI agent can access, just like you would for any automated process.\n\n**\u26a0\ufe0f Data Privacy:** Database content will be sent to your LLM provider. Only connect to databases containing data you have the right to share. Consider data protection regulations (GDPR, HIPAA, etc.) and your organization's policies before use.\n\n**\u26a0\ufe0f Unrestricted Mode (Dangerous)**\n\nOnly connect to databases you're willing to destroy. Allows full write access and DDL. Add `--access-mode=unrestricted` to the args array as shown in the `uv` example above.\n\n\n##### Logging Configuration\n\nWhen using stdio transport (the default), Postgres MCP Lite writes logs to stderr to avoid interfering with the MCP protocol (which uses stdout). When using SSE transport, logs go to stdout.\n\nYou can control the logging verbosity using the `LOG_LEVEL` environment variable:\n\n- `DEBUG` - Show all logs including debug messages\n- `INFO` - Show info, warning, and error messages (default)\n- `WARNING` - Show only warnings and errors\n- `ERROR` - Show only errors\n- `CRITICAL` - Show only critical errors\n- `NONE` - Disable all logging\n\nExample configuration with logging disabled:\n\n```json\n{\n \"mcpServers\": {\n \"postgres\": {\n \"command\": \"pg-mcp\",\n \"env\": {\n \"DATABASE_URI\": \"postgresql://username:password@localhost:5432/dbname\",\n \"LOG_LEVEL\": \"NONE\"\n }\n }\n }\n}\n```\n\n\n#### Claude Code Configuration\n\n[Claude Code](https://docs.claude.com/en/docs/claude-code/overview) is Anthropic's agentic coding tool for your terminal. To configure Postgres MCP Lite with Claude Code:\n\n1. **Install Claude Code** (if you haven't already):\n ```bash\n npm install -g @anthropic-ai/claude-code\n ```\n\n2. **Edit your Claude Code configuration file**:\n - Location: `~/.claude.json` (Linux/macOS) or `%USERPROFILE%\\.claude.json` (Windows)\n - Or use the CLI wizard: `claude mcp add`\n\n3. **Add Postgres MCP Lite to your configuration**:\n\n ```json\n {\n \"mcpServers\": {\n \"postgres\": {\n \"command\": \"pg-mcp\",\n \"env\": {\n \"DATABASE_URI\": \"postgresql://username:password@localhost:5432/dbname\"\n }\n }\n }\n }\n ```\n\n4. **Restart Claude Code** for changes to take effect. Verify with:\n ```bash\n claude mcp list\n ```\n\n#### Other MCP Clients\n\nMany MCP clients have similar configuration files to Claude Desktop, and you can adapt the examples above to work with the client of your choice.\n\n- If you are using Cursor, you can use navigate from the `Command Palette` to `Cursor Settings`, then open the `MCP` tab to access the configuration file.\n- If you are using Windsurf, you can navigate to from the `Command Palette` to `Open Windsurf Settings Page` to access the configuration file.\n- If you are using Goose run `goose configure`, then select `Add Extension`.\n\n## SSE Transport\n\nPostgres MCP Lite supports the [SSE transport](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse), which allows multiple MCP clients to share one server, possibly a remote server.\nTo use the SSE transport, you need to start the server with the `--transport=sse` option.\n\nFor example, run:\n\n```bash\nDATABASE_URI=postgresql://username:password@localhost:5432/dbname \\\n pg-mcp --transport=sse\n```\n\nThen update your MCP client configuration to call the MCP server.\nFor example, in Cursor's `mcp.json` or Cline's `cline_mcp_settings.json` you can put:\n\n```json\n{\n \"mcpServers\": {\n \"postgres\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:8000/sse\"\n }\n }\n}\n```\n\nFor Windsurf, the format in `mcp_config.json` is slightly different:\n\n```json\n{\n \"mcpServers\": {\n \"postgres\": {\n \"type\": \"sse\",\n \"serverUrl\": \"http://localhost:8000/sse\"\n }\n }\n}\n```\n\n## Usage Examples\n\n### Explore Database Schema\n\nAsk:\n> Show me all the tables in the database and their structure.\n\n### Generate SQL Queries\n\nAsk:\n> Write a query to find all orders from the past month with their customer details.\n\n### Analyze Table Structure\n\nAsk:\n> What indexes exist on the orders table and what columns do they cover?\n\n### Execute Data Queries\n\nAsk:\n> Show me the top 10 customers by order count in 2024.\n\n## MCP Server API\n\nThe [MCP standard](https://modelcontextprotocol.io/) defines various types of endpoints: Tools, Resources, Prompts, and others.\n\nPostgres MCP Lite provides functionality via [MCP tools](https://modelcontextprotocol.io/docs/concepts/tools) alone.\nWe chose this approach because the [MCP client ecosystem](https://modelcontextprotocol.io/clients) has widespread support for MCP tools.\nThis contrasts with the approach of other Postgres MCP servers, including the [Reference Postgres MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres), which use [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) to expose schema information.\n\n\nPostgres MCP Lite provides 4 essential tools:\n\n| Tool Name | Description |\n|-----------|-------------|\n| `list_schemas` | Lists all database schemas available in the PostgreSQL instance. |\n| `list_objects` | Lists database objects (tables, views, sequences, extensions) within a specified schema. |\n| `get_object_details` | Provides detailed information about a specific database object, including columns, constraints, and indexes. |\n| `execute_sql` | Executes SQL statements on the database, with read-only limitations when connected in restricted mode. |\n\n\n## Related Projects\n\n**Other Postgres MCP Servers**\n- [Reference PostgreSQL MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres) - Official reference implementation\n- [PG-MCP](https://github.com/stuzero/pg-mcp-server) - Feature-rich PostgreSQL MCP server\n- [Supabase Postgres MCP Server](https://github.com/supabase-community/supabase-mcp) - Supabase integration\n- [Query MCP](https://github.com/alexander-zuev/supabase-mcp-server) - Three-tier safety architecture\n\n## Technical Notes\n\n### Postgres Client Library\n\nPostgres MCP Lite uses [psycopg3](https://www.psycopg.org/) in **synchronous mode** for reliable database connectivity. It leverages [libpq](https://www.postgresql.org/docs/current/libpq.html) for full Postgres feature support.\n\n### Safe SQL Execution by Default\n\nPostgres MCP Lite **defaults to restricted mode** for safe data exploration:\n\n- **Restricted Mode (Default)**: Read-only transactions with SQL validation and execution time limits. Perfect for production databases.\n- **Unrestricted Mode**: Full read/write access for development or when explicitly needed.\n\nIn restricted mode, SQL is parsed using [pglast](https://pglast.readthedocs.io/) to validate that only safe, read-only operations are allowed (SELECT, EXPLAIN, SHOW, ANALYZE, VACUUM). All queries execute within read-only transactions and are automatically rolled back, preventing accidental data modifications.\n\n### Schema Information\n\nSchema tools provide AI agents with the information needed to generate correct SQL. While LLMs can query Postgres system catalogs directly, dedicated tools ensure consistent, reliable schema exploration across different LLM capabilities.\n\n\n## Postgres MCP Lite Development\n\nThe instructions below are for developers who want to work on Postgres MCP Lite, or users who prefer to install Postgres MCP Lite from source.\n\n### Local Development Setup\n\n1. **Install uv**:\n\n ```bash\n curl -sSL https://astral.sh/uv/install.sh | sh\n ```\n\n2. **Clone the repository**:\n\n ```bash\n git clone https://github.com/andre-c-andersen/pg-mcp.git\n cd pg-mcp\n ```\n\n3. **Install dependencies**:\n\n ```bash\n uv pip install -e .\n uv sync\n ```\n\n4. **Run the server**:\n ```bash\n uv run pg-mcp \"postgres://user:password@localhost:5432/dbname\"\n ```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight, read-only-by-default PostgreSQL MCP server for data analysts and ETL developers",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/andre-c-andersen/pg-mcp",
"Issues": "https://github.com/andre-c-andersen/pg-mcp/issues",
"Original Project": "https://github.com/crystaldba/postgres-mcp",
"Repository": "https://github.com/andre-c-andersen/pg-mcp"
},
"split_keywords": [
"ai",
" database",
" llm",
" mcp",
" model-context-protocol",
" postgres",
" postgresql"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "df50ea3079a4499326ec1e0592bf19a393101d82834ba2a01978d19163b3fc8c",
"md5": "5678098af9b8fd9044ba6c24be31eeee",
"sha256": "cecc2eaefc989bf946f5b6e540abd96f8a2bedf2a57f7e4e10479578d19ee1ef"
},
"downloads": -1,
"filename": "pg_mcp-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5678098af9b8fd9044ba6c24be31eeee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 34465,
"upload_time": "2025-10-19T14:31:28",
"upload_time_iso_8601": "2025-10-19T14:31:28.849311Z",
"url": "https://files.pythonhosted.org/packages/df/50/ea3079a4499326ec1e0592bf19a393101d82834ba2a01978d19163b3fc8c/pg_mcp-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cb0fbf22e30d1657baa9423974605b052ed71ae6f3feea826583d4105d81a1f0",
"md5": "c7ee64270d58fc8bee366b96f2b828dc",
"sha256": "b01c67164389fcda0ac9be15e6714d8f464dea3510d4b984579df41518936afb"
},
"downloads": -1,
"filename": "pg_mcp-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "c7ee64270d58fc8bee366b96f2b828dc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 133126,
"upload_time": "2025-10-19T14:31:30",
"upload_time_iso_8601": "2025-10-19T14:31:30.537857Z",
"url": "https://files.pythonhosted.org/packages/cb/0f/bf22e30d1657baa9423974605b052ed71ae6f3feea826583d4105d81a1f0/pg_mcp-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-19 14:31:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "andre-c-andersen",
"github_project": "pg-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pg-mcp"
}
JSON
