# mcp-postgres-query

MCP server that connects Claude to any PostgreSQL database. Explore schemas, run queries, analyze performance — all through natural conversation.

Built by [THRYXAGI](https://github.com/lordbasilaiassistant-sudo).

## Install

```bash
npm install -g mcp-postgres-query
```

Or run directly:

```bash
npx mcp-postgres-query
```

## Configuration

Set the `DATABASE_URL` environment variable with your PostgreSQL connection string:

```
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "mcp-postgres-query"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}
```

### Claude Code

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "mcp-postgres-query"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}
```

## Tools (7)

| Tool | Description | Params |
|------|-------------|--------|
| `query` | Execute a SQL query | `sql` (string), `params` (optional array) |
| `list_tables` | List all tables in the public schema | none |
| `describe_table` | Get column details (type, nullable, default) | `table_name` |
| `list_indexes` | List indexes on a table | `table_name` |
| `explain_query` | Get EXPLAIN ANALYZE plan (safe, rolls back) | `sql` |
| `get_table_stats` | Row counts and table size | `table_name` |
| `get_db_info` | Database overview (version, size, table count) | none |

## Example Usage

Once connected, ask Claude things like:

- "What tables are in this database?"
- "Describe the users table"
- "SELECT * FROM orders WHERE created_at > '2024-01-01' LIMIT 10"
- "Explain this slow query: SELECT ..."
- "How big is the events table?"

## Security Notes

- The `query` tool executes arbitrary SQL. Connect with a **read-only database user** for safety.
- The `explain_query` tool wraps EXPLAIN ANALYZE in a transaction that always rolls back, so it never modifies data.
- Parameterized queries are supported via the `params` argument to prevent SQL injection.
- Never expose `DATABASE_URL` in public repositories or logs.

## License

MIT