# PostgreSQL MCP server

> Allows an AI client to inspect schemas, execute read-only queries, and analyze indexes within a PostgreSQL database.

- Repository: https://github.com/musaddiq-dev/postgresql-mcp-server
- Page: https://hostedmcp.org/servers/musaddiq-dev/postgresql-mcp-server
- Transport: stdio
- Stars: 1
- License: MIT
- Latest version: 0.1.2

## Install

### Claude Code

```sh
claude mcp add --env 'POSTGRES_DB=<POSTGRES_DB>' --env 'POSTGRES_HOST=<POSTGRES_HOST>' --env 'POSTGRES_PORT=<POSTGRES_PORT>' --env 'POSTGRES_USER=<POSTGRES_USER>' --env 'POSTGRES_PASSWORD=<YOUR_POSTGRES_PASSWORD>' postgresql-mcp-server -- uvx mdev-postgresql-mcp-server
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "postgresql-mcp-server": {
      "command": "uvx",
      "args": [
        "mdev-postgresql-mcp-server"
      ],
      "env": {
        "POSTGRES_DB": "<POSTGRES_DB>",
        "POSTGRES_HOST": "<POSTGRES_HOST>",
        "POSTGRES_PORT": "<POSTGRES_PORT>",
        "POSTGRES_USER": "<POSTGRES_USER>",
        "POSTGRES_PASSWORD": "<YOUR_POSTGRES_PASSWORD>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "postgresql-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mdev-postgresql-mcp-server"
      ],
      "env": {
        "POSTGRES_DB": "<POSTGRES_DB>",
        "POSTGRES_HOST": "<POSTGRES_HOST>",
        "POSTGRES_PORT": "<POSTGRES_PORT>",
        "POSTGRES_USER": "<POSTGRES_USER>",
        "POSTGRES_PASSWORD": "<YOUR_POSTGRES_PASSWORD>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"postgresql-mcp-server","type":"stdio","command":"uvx","args":["mdev-postgresql-mcp-server"],"env":{"POSTGRES_DB":"<POSTGRES_DB>","POSTGRES_HOST":"<POSTGRES_HOST>","POSTGRES_PORT":"<POSTGRES_PORT>","POSTGRES_USER":"<POSTGRES_USER>","POSTGRES_PASSWORD":"<YOUR_POSTGRES_PASSWORD>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "postgresql-mcp-server": {
      "command": "uvx",
      "args": [
        "mdev-postgresql-mcp-server"
      ],
      "env": {
        "POSTGRES_DB": "<POSTGRES_DB>",
        "POSTGRES_HOST": "<POSTGRES_HOST>",
        "POSTGRES_PORT": "<POSTGRES_PORT>",
        "POSTGRES_USER": "<POSTGRES_USER>",
        "POSTGRES_PASSWORD": "<YOUR_POSTGRES_PASSWORD>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add postgresql-mcp-server --env 'POSTGRES_DB=<POSTGRES_DB>' --env 'POSTGRES_HOST=<POSTGRES_HOST>' --env 'POSTGRES_PORT=<POSTGRES_PORT>' --env 'POSTGRES_USER=<POSTGRES_USER>' --env 'POSTGRES_PASSWORD=<YOUR_POSTGRES_PASSWORD>' -- uvx mdev-postgresql-mcp-server
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.postgresql-mcp-server]
command = "uvx"
args = ["mdev-postgresql-mcp-server"]

[mcp_servers.postgresql-mcp-server.env]
POSTGRES_DB = "<POSTGRES_DB>"
POSTGRES_HOST = "<POSTGRES_HOST>"
POSTGRES_PORT = "<POSTGRES_PORT>"
POSTGRES_USER = "<POSTGRES_USER>"
POSTGRES_PASSWORD = "<YOUR_POSTGRES_PASSWORD>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'POSTGRES_DB=<POSTGRES_DB>' -e 'POSTGRES_HOST=<POSTGRES_HOST>' -e 'POSTGRES_PORT=<POSTGRES_PORT>' -e 'POSTGRES_USER=<POSTGRES_USER>' -e 'POSTGRES_PASSWORD=<YOUR_POSTGRES_PASSWORD>' postgresql-mcp-server uvx -- mdev-postgresql-mcp-server
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "postgresql-mcp-server": {
      "command": "uvx",
      "args": [
        "mdev-postgresql-mcp-server"
      ],
      "env": {
        "POSTGRES_DB": "<POSTGRES_DB>",
        "POSTGRES_HOST": "<POSTGRES_HOST>",
        "POSTGRES_PORT": "<POSTGRES_PORT>",
        "POSTGRES_USER": "<POSTGRES_USER>",
        "POSTGRES_PASSWORD": "<YOUR_POSTGRES_PASSWORD>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `POSTGRES_DB` | yes | no | PostgreSQL database name |
| `POSTGRES_HOST` | yes | no | PostgreSQL host |
| `POSTGRES_PORT` | yes | no | PostgreSQL port |
| `POSTGRES_USER` | yes | no | PostgreSQL username |
| `POSTGRES_PASSWORD` | no | yes | PostgreSQL password |
| `POSTGRES_READ_QUERY_LIMIT` | no | no | Maximum rows returned by read queries |

## Tools (10)

- `postgresql_list_tables`
- `postgresql_describe_table`
- `postgresql_execute_read_query`
- `postgresql_execute_write_query`
- `postgresql_explain_query`
- `postgresql_get_database_summary`
- `postgresql_get_relationships`
- `postgresql_analyze_indexes`
- `postgresql_preview_table`
- `postgresql_search_sql_definitions`

## FAQ

### Is it safe to run queries with this server?

The server provides a read-only tool that runs in a PostgreSQL read-only transaction mode and rolls back after execution to ensure safety.

### Can the server modify my database?

Yes, the `postgresql_execute_write_query` tool can modify data or schema if the connected user has permission, so it should be used with caution.

### What are the system requirements?

You need Python 3.11 or higher and a PostgreSQL database.
