# mcp-postgres

An MCP server that connects to a PostgreSQL database and exposes schema inspection and safe query execution as tools and resources — ready to plug into Claude Desktop or any MCP-compatible client.

## Tools

| Tool | Description |
|------|-------------|
| `list_tables` | List all tables in the public schema |
| `describe_table(table_name)` | Show columns, types, and nullability for a table |
| `run_query(query)` | Execute a SELECT query and return results (mutating statements are blocked) |

## Resources

| URI | Description |
|-----|-------------|
| `schema://tables` | Full schema dump — all tables with their columns |

## Setup

### 1. Clone and install

```bash
git clone <repo-url>
cd mcp-postgres
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
```

### 2. Configure environment

```bash
cp .env.example .env
# Edit .env — set DATABASE_URL to your PostgreSQL connection string
```

### 3. Run the server

```bash
mcp-postgres
```

Or directly:

```bash
python -m mcp_postgres.server
```

## Claude Desktop Integration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "postgres": {
      "command": "/path/to/.venv/bin/mcp-postgres",
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}
```

## Project Structure

```
src/mcp_postgres/
  __init__.py   — package marker
  db.py         — psycopg2 connection context manager
  server.py     — FastMCP server, tools, and resources
```

## Security

`run_query` rejects any statement that does not begin with `SELECT`. This prevents accidental or malicious data modification through the MCP interface.