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:

{
  "schema": "public"
}

describe_table

Describes a table in a schema.

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

execute_query

Runs a read-only PostgreSQL query.

{
  "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.

{
  "schema": "public"
}

Tech Stack

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

Setup

Install dependencies:

npm install

Set your database connection string:

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

On Windows PowerShell:

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

Run

npx tsx src/index.ts

Type Check

npx tsc --noEmit