# pg-mcp-bridge (MCP server source)

Local **stdio MCP bridge** for **Cursor** and **Claude Code** so you can talk to a remote PostgreSQL database through a **PHP/Apache HTTP tunnel**.

- **This repo:** Node MCP bridge source → published as npm [`pg-mcp-bridge`](https://www.npmjs.com/package/pg-mcp-bridge)
- **PHP tunnel:** download from [Rabin0404/pg-mcp-bridge](https://github.com/Rabin0404/pg-mcp-bridge) and upload to your PHP host

```text
Cursor / Claude Code  →  pg-mcp-bridge  →  HTTPS  →  PHP tunnel  →  PostgreSQL
```

## PHP tunnel (required on your server)

Upload the PHP files from **https://github.com/Rabin0404/pg-mcp-bridge**:

- `pg_mcp_tunnel.php`
- `config.example.php` → copy to `config.php` and set DB credentials + bearer token
- `.htaccess` (optional; blocks web access to `config.php`)

See that repo’s README for `access_mode` (`readonly` | `readwrite` | `full`) and curl test steps.

## Claude Code setup

### Option A — project `.mcp.json`

Copy [`examples/claude.mcp.json`](examples/claude.mcp.json) to your project root as `.mcp.json` (or merge into an existing one), then set the env values:

```json
{
  "mcpServers": {
    "remote-postgres": {
      "command": "npx",
      "args": ["-y", "pg-mcp-bridge"],
      "env": {
        "PG_MCP_TUNNEL_URL": "https://your-domain.com/pg_mcp_tunnel.php",
        "PG_MCP_TOKEN": "your-bearer-token"
      }
    }
  }
}
```

Claude Code also supports `${VAR}` expansion, for example:

```json
"env": {
  "PG_MCP_TUNNEL_URL": "${PG_MCP_TUNNEL_URL}",
  "PG_MCP_TOKEN": "${PG_MCP_TOKEN}"
}
```

### Option B — CLI

```bash
claude mcp add --transport stdio remote-postgres \
  --env PG_MCP_TUNNEL_URL=https://your-domain.com/pg_mcp_tunnel.php \
  --env PG_MCP_TOKEN=your-bearer-token \
  -- npx -y pg-mcp-bridge
```

Scopes: `local` (default), `project` (shared `.mcp.json`), or `user` (all projects). See [Claude Code MCP docs](https://code.claude.com/docs/en/mcp).

Verify:

```bash
claude mcp list
claude mcp get remote-postgres
```

## Cursor setup

Add to Cursor MCP settings (`mcp.json`):

```json
{
  "mcpServers": {
    "remote-postgres": {
      "command": "npx",
      "args": ["-y", "pg-mcp-bridge"],
      "env": {
        "PG_MCP_TUNNEL_URL": "https://your-domain.com/pg_mcp_tunnel.php",
        "PG_MCP_TOKEN": "your-bearer-token"
      }
    }
  }
}
```

## Develop locally

```bash
npm install
npm run build
node dist/index.js
```

## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PG_MCP_TUNNEL_URL` | Yes | Full URL to `pg_mcp_tunnel.php` |
| `PG_MCP_TOKEN` | Yes | Same bearer token as in server `config.php` |

## MCP tools

- `ping` — connectivity + `access_mode`
- `list_schemas`
- `list_tables`
- `describe_table`
- `query` — SQL allowed by server `access_mode`

## License

MIT