# PostgreSQL MCP server

> Enables AI agents to interact with PostgreSQL databases using specialized tools, schema introspection, and a secure V8 isolate for complex operations.

- Repository: https://github.com/neverinfamous/postgres-mcp
- Page: https://hostedmcp.org/servers/neverinfamous/postgres-mcp
- Transport: stdio
- Stars: 12
- License: MIT
- Latest version: 1.2.0

## Install

### Claude Code

```sh
claude mcp add postgres-mcp -- docker run -i --rm docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0
```

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

```json
{
  "mcpServers": {
    "postgres-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0"
      ]
    }
  }
}
```

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

```json
{
  "servers": {
    "postgres-mcp": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"postgres-mcp","type":"stdio","command":"docker","args":["run","-i","--rm","docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0"]}'
```

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

```json
{
  "mcpServers": {
    "postgres-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add postgres-mcp -- docker run -i --rm docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0
```

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

```toml
[mcp_servers.postgres-mcp]
command = "docker"
args = ["run", "-i", "--rm", "docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0"]
```

### Gemini CLI

```sh
gemini mcp add -s user postgres-mcp docker -- run -i --rm docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0
```

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

```json
{
  "mcpServers": {
    "postgres-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `MCP_AUTH_TOKEN` | no | no |  |
| `POSTGRES_DATABASE` | no | no |  |
| `POSTGRES_HOST` | no | no |  |
| `POSTGRES_PASSWORD` | no | no |  |
| `POSTGRES_PORT` | no | no |  |
| `POSTGRES_USER` | no | no |  |

## Tools (25)

- `codemode`
- `core`
- `transactions`
- `jsonb`
- `text`
- `performance`
- `admin`
- `monitoring`
- `backup`
- `schema`
- `introspection`
- `migration`
- `partitioning`
- `stats`
- `vector`
- `postgis`
- `cron`
- `partman`
- `kcache`
- `citext`
- `ltree`
- `pgcrypto`
- `security`
- `roles`
- `docstore`

## FAQ

### How can I reduce token usage when performing complex database operations?

You can use 'Code Mode', which executes operations inside a secure V8 isolate to reduce AI overhead by up to 90%.

### How does the server handle database errors for AI agents?

It uses deterministic error handling to intercept raw SQL exceptions and translate them into clear, actionable advice to prevent AI hallucinations.

### Can I restrict the tools available to the AI?

Yes, you can use the --tool-filter argument to dynamically compile the server with specific tool groups or individual tool names.
