npm package: @siranjeevik/azure-postgres-mcp
Description: Custom MCP server for Azure PostgreSQL — query, inspect, and explore your database from Claude Code
Author: Siranjeevi K
Latest version: 0.1.0

# azure-postgres-mcp

A custom-built MCP server that lets Claude Code (or any MCP client) query your Azure PostgreSQL database.

## Why

Built in-house to give Claude Code direct access to Azure PostgreSQL databases for day-to-day exploration and development — without relying on third-party MCP servers where you can't fully audit what SQL gets executed or what data leaves your environment.

## Tools

| Tool              | Description                                                    |
| ----------------- | -------------------------------------------------------------- |
| `query`           | Run a read-only SQL query (wrapped in a read-only transaction) |
| `execute`         | Run a write SQL statement (INSERT, UPDATE, DELETE, DDL)        |
| `list_tables`     | List all tables and views, optionally filtered by schema       |
| `describe_table`  | Show columns, types, nullability, defaults, and primary keys   |
| `list_indexes`    | List indexes on a table with columns and uniqueness            |
| `foreign_keys`    | Show foreign key relationships for a table                     |
| `table_sizes`     | Show disk usage for all tables, sorted by size                 |
| `schema_overview` | High-level overview of schemas, table counts, and DB size      |

## Setup

### 1. Install dependencies

```bash
cd azure-postgres-mcp
npm install
```

### 2. Configure your database connection

Copy the example and fill in your credentials:

```bash
cp .env.example .env
# Edit .env with your actual credentials
```

**Azure PostgreSQL:**

```env
DATABASE_URL=postgresql://user:pass@your-server.postgres.database.azure.com:5432/dbname
# DB_SSL defaults to true — required by Azure, leave it unset
```

**Local / Docker (e.g. [sakiladb/postgres](https://hub.docker.com/r/sakiladb/postgres)):**

```bash
docker run --name sakila-postgres -p 5432:5432 -e POSTGRES_PASSWORD=test sakiladb/postgres
```

```env
DATABASE_URL=postgresql://sakila:p_ssW0rd@localhost:5432/sakila
DB_SSL=false
```

> The `sakiladb/postgres` image uses `sakila` as the superuser (not `postgres`).
> Verify with: `docker exec sakila-postgres psql -U sakila -c "\du"`

### 3. Build

```bash
npm run build
```

### 4. Register with Claude Code

**Option A — CLI command:**

```bash
# User scope (available across all your projects)
claude mcp add azure-postgres -s user -- node /absolute/path/to/azure-postgres-mcp/dist/server.js

# Project scope (stored in .mcp.json, shared with the repo)
claude mcp add azure-postgres -s project -- node ./dist/server.js
```

**Option B — Project `.mcp.json`** (place in your project root):

```json
{
  "mcpServers": {
    "azure-postgres": {
      "command": "node",
      "args": ["/absolute/path/to/azure-postgres-mcp/dist/server.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@your-server.postgres.database.azure.com:5432/dbname?sslmode=require"
      }
    }
  }
}
```

### 5. Verify

Open Claude Code and run:

```
/mcp
```

You should see `azure-postgres` listed. Try asking:

> "What tables are in my database?"

## Security notes

- The `query` tool enforces read-only transactions — it cannot accidentally modify data.
- The `execute` tool allows writes. Remove it from `src/server.ts` if you want a fully read-only server.
- SSL is enabled by default (required by Azure). Set `DB_SSL=false` for local/Docker connections.
- Never commit your `.env` file. Add it to `.gitignore`.

## Making it read-only

If you want to remove write access entirely, delete the `execute` tool block from `src/server.ts` and rebuild. Or better yet, use a Postgres role with only `SELECT` privileges.