# MCP PostgreSQL Explorer

MCP PostgreSQL Explorer is a TypeScript MCP server that lets AI clients explore a PostgreSQL database schema and run read-only queries.

This is my first project of this kind. I am a computer science student building it to learn how MCP servers, TypeScript, PostgreSQL introspection, and database tooling work together.

## Features

- Lists base tables in a PostgreSQL schema.
- Describes table columns, data types, defaults, nullability, and constraints.
- Runs `SELECT`-only queries.
- Lists foreign key relationships between tables.
- Uses `public` as the default schema, with an optional schema override.

## Tools

### `list_tables`

Lists base tables in a schema.

Default:

```json
{
  "schema": "public"
}
```

### `describe_table`

Describes a table in a schema.

```json
{
  "schema": "public",
  "table": "users"
}
```

### `execute_query`

Runs a read-only PostgreSQL query.

```json
{
  "query": "SELECT * FROM users LIMIT 10",
  "params": []
}
```

The tool rejects mutations, semicolons, and non-`SELECT` statements.

### `get_relationships`

Lists foreign key relationships for tables in a schema.

```json
{
  "schema": "public"
}
```

## Tech Stack

- TypeScript
- Node.js
- `@modelcontextprotocol/sdk`
- `pg`
- PostgreSQL system catalogs and `information_schema`

## Setup

Install dependencies:

```bash
npm install
```

Set your database connection string:

```bash
export DATABASE_URL="postgres://user:password@localhost:5432/database_name"
```

On Windows PowerShell:

```powershell
$env:DATABASE_URL="postgres://user:password@localhost:5432/database_name"
```

## Run

```bash
npx tsx src/index.ts
```

## Type Check

```bash
npx tsc --noEmit
```