# easy-pg-admin-mcp

High-privilege PostgreSQL admin MCP server for database and role/grant management.

This project is a DBA-style tool. It does not provide raw SQL execution and does not manage tables, schemas, views, indexes, triggers, or functions. Use `easy-pg-mcp` for data access and schema/table operations.

## Features

- List, create, inspect, and change owners for databases
- List, create, update, and drop PostgreSQL roles
- Grant and revoke role memberships
- Grant and revoke database-level privileges
- Protect destructive actions with short-lived confirmation tokens

## Available Tools

| Tool | Description |
| --- | --- |
| `pg_list_databases` | List databases in the current PostgreSQL instance |
| `pg_create_database` | Create a PostgreSQL database |
| `pg_describe_database` | Inspect a PostgreSQL database |
| `pg_alter_database_owner` | Change a database owner |
| `pg_drop_database` | Request database deletion and return a confirmation token |
| `pg_list_roles` | List PostgreSQL roles |
| `pg_create_role` | Create a PostgreSQL role without SUPERUSER support |
| `pg_alter_role_password` | Change a role password |
| `pg_alter_role_attributes` | Change supported role attributes |
| `pg_drop_role` | Request role deletion and return a confirmation token |
| `pg_grant_role` | Grant a role to another role |
| `pg_revoke_role` | Revoke a role from another role |
| `pg_show_role_memberships` | Show memberships for a role |
| `pg_grant_privileges` | Grant database-level privileges to a role |
| `pg_revoke_privileges` | Revoke database-level privileges from a role |
| `pg_show_grants` | Show database-level grants for a role |
| `pg_confirm_task` | Confirm and execute a destructive action token |

## Safety

- No raw SQL passthrough
- No schema, table, view, index, trigger, or function management
- SUPERUSER role creation and modification are not supported
- `pg_drop_database` and `pg_drop_role` require `pg_confirm_task`
- `pg_drop_role` does not support `REASSIGN OWNED` or `DROP OWNED`
- Confirmation tokens are random, single-use, and expire quickly

## Configuration

Use environment variables, matching the rest of the `easy-*-mcp` family.

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `PG_CONNECTION_STRING` | Conditional | - | PostgreSQL connection string. Takes precedence when provided |
| `PG_HOST` | Conditional | - | PostgreSQL host when no connection string is provided |
| `PG_PORT` | No | `5432` | PostgreSQL port |
| `PG_USER` | Conditional | - | PostgreSQL admin role name when no connection string is provided |
| `PG_PASSWORD` | No | - | PostgreSQL password |
| `PG_DATABASE` | Conditional | - | Default database used for the admin connection |
| `PG_CONNECTION_LIMIT` | No | `10` | Maximum number of active pool connections |
| `PG_CONNECTION_TIMEOUT` | No | `10000` | Connection establishment timeout in milliseconds |
| `PG_IDLE_TIMEOUT` | No | `30000` | Idle connection timeout in milliseconds |
| `PG_ENABLE_KEEP_ALIVE` | No | `true` | Whether TCP keep-alive is enabled |
| `PG_KEEP_ALIVE_INITIAL_DELAY` | No | `0` | Initial TCP keep-alive delay in milliseconds |
| `PG_SSL` | No | `false` | Use `true`, `false`, or `no-verify` |
| `PG_ADMIN_TOKEN_TTL_SECONDS` | No | `120` | Confirmation token lifetime in seconds |

## Example

```env
PG_HOST=localhost
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=your_password
PG_DATABASE=postgres
PG_SSL=false
PG_ADMIN_TOKEN_TTL_SECONDS=120
```

## Claude Desktop Example

```json
{
  "mcpServers": {
    "easy-pg-admin-mcp": {
      "command": "npx",
      "args": ["-y", "easy-pg-admin-mcp"],
      "env": {
        "PG_HOST": "localhost",
        "PG_PORT": "5432",
        "PG_USER": "postgres",
        "PG_PASSWORD": "your_password",
        "PG_DATABASE": "postgres",
        "PG_SSL": "false",
        "PG_ADMIN_TOKEN_TTL_SECONDS": "120"
      }
    }
  }
}
```

## Codex config.toml Example

```
[mcp_servers.easy-pg-admin-mcp]
args = ["-y", "easy-pg-admin-mcp"]
command = "npx"
enabled = true

[mcp_servers.easy-pg-admin-mcp.env]
PG_HOST = "localhost"
PG_PORT = "5432"
PG_USER = "postgres"
PG_PASSWORD = "your_password"
PG_DATABASE = "postgres"
PG_SSL = "false"
PG_ADMIN_TOKEN_TTL_SECONDS = "120"
```

## OpenCode opencode.jsonc Example

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "easy-pg-admin-mcp": {
      "type": "local",
      "command": ["npx", "-y", "easy-pg-admin-mcp"],
      "enabled": true,
      "environment": {
        "PG_HOST": "localhost",
        "PG_PORT": "5432",
        "PG_USER": "postgres",
        "PG_PASSWORD": "your_password",
        "PG_DATABASE": "postgres",
        "PG_SSL": "false",
        "PG_ADMIN_TOKEN_TTL_SECONDS": "120",
      },
    },
  },
}
```