@marcelo-ochoa/server-postgres 0.6.2

package/README.md

@@ -0,0 +1,164 @@
+# PostgreSQL
+
+A Model Context Protocol server that provides read-only access to PostgreSQL databases. This server enables LLMs to inspect database schemas and execute read-only queries.
+
+## Components
+
+### Tools
+
+- **pg-query**
+  - Execute read-only SQL queries against the connected database
+  - Input: `sql` (string): The SQL query to execute
+  - All queries are executed within a READ ONLY transaction
+
+- **pg-stats**
+  - Get statistics for a specific table
+  - Input: `name` (string): The name of the table to get statistics for
+
+- **pg-explain**
+  - Explain Plan for a given SQL query
+  - Input: `sql` (string): The SQL query to explain
+
+- **pg-connect**
+  - Connect to a PostgreSQL database
+  - Input: `connectionString` (string): The PostgreSQL connection string (e.g. postgresql://user:password@host:port/dbname)
+
+- **pg-awr**
+  - Generate a PostgreSQL performance report similar to Oracle AWR. Includes database statistics, top queries (requires pg_stat_statements extension), table/index statistics, connection info, and optimization recommendations.
+
+### Resources
+
+The server provides schema information for each table in the database:
+
+- **Table Schemas** (`postgres://<host>/<table>/schema`)
+  - JSON schema information for each table
+  - Includes column names and data types
+  - Automatically discovered from database metadata
+
+## Configuration
+
+### Usage with Claude Desktop
+
+To use this server with the Claude Desktop app, add the following configuration to the "mcpServers" section of your `claude_desktop_config.json`:
+
+### Docker
+
+* when running docker on macos, use host.docker.internal if the server is running on the host network (eg localhost)
+* username/password can be added to the postgresql url with `postgresql://user:password@host:port/db-name`
+
+```json
+{
+  "mcpServers": {
+    "postgres": {
+      "command": "docker",
+      "args": [
+        "run", 
+        "-i", 
+        "--rm", 
+        "mochoa/mcp-postgres", 
+        "postgresql://host.docker.internal:5432/mydb"]
+    }
+  }
+}
+```
+
+### NPX
+
+```json
+{
+  "mcpServers": {
+    "postgres": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@marcelo-ochoa/server-postgres",
+        "postgresql://localhost/mydb"
+      ]
+    }
+  }
+}
+```
+
+Replace `/mydb` with your database name.
+
+### Usage with VS Code
+
+For quick installation, use one of the one-click install buttons below...
+
+[![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=postgres&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22pg_url%22%2C%22description%22%3A%22PostgreSQL%20URL%20(e.g.%20postgresql%3A%2F%2Fuser%3Apass%40localhost%3A5432%2Fmydb)%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-postgres%22%2C%22%24%7Binput%3Apg_url%7D%22%5D%7D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-NPM-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=postgres&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22pg_url%22%2C%22description%22%3A%22PostgreSQL%20URL%20(e.g.%20postgresql%3A%2F%2Fuser%3Apass%40localhost%3A5432%2Fmydb)%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-postgres%22%2C%22%24%7Binput%3Apg_url%7D%22%5D%7D&quality=insiders)
+
+[![Install with Docker in VS Code](https://img.shields.io/badge/VS_Code-Docker-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=postgres&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22pg_url%22%2C%22description%22%3A%22PostgreSQL%20URL%20(e.g.%20postgresql%3A%2F%2Fuser%3Apass%40host.docker.internal%3A5432%2Fmydb)%22%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22mcp%2Fpostgres%22%2C%22%24%7Binput%3Apg_url%7D%22%5D%7D) [![Install with Docker in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Docker-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=postgres&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22pg_url%22%2C%22description%22%3A%22PostgreSQL%20URL%20(e.g.%20postgresql%3A%2F%2Fuser%3Apass%40host.docker.internal%3A5432%2Fmydb)%22%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22mcp%2Fpostgres%22%2C%22%24%7Binput%3Apg_url%7D%22%5D%7D&quality=insiders)
+
+For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.
+
+Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
+
+> Note that the `mcp` key is not needed in the `.vscode/mcp.json` file.
+
+### Docker
+
+**Note**: When using Docker and connecting to a PostgreSQL server on your host machine, use `host.docker.internal` instead of `localhost` in the connection URL.
+
+```json
+{
+  "mcp": {
+    "inputs": [
+      {
+        "type": "promptString",
+        "id": "pg_url",
+        "description": "PostgreSQL URL (e.g. postgresql://user:pass@host.docker.internal:5432/mydb)"
+      }
+    ],
+    "servers": {
+      "postgres": {
+        "command": "docker",
+        "args": [
+          "run",
+          "-i",
+          "--rm",
+          "mochoa/mcp-postgres",
+          "${input:pg_url}"
+        ]
+      }
+    }
+  }
+}
+```
+
+### NPX
+
+```json
+{
+  "mcp": {
+    "inputs": [
+      {
+        "type": "promptString",
+        "id": "pg_url",
+        "description": "PostgreSQL URL (e.g. postgresql://user:pass@localhost:5432/mydb)"
+      }
+    ],
+    "servers": {
+      "postgres": {
+        "command": "npx",
+        "args": [
+          "-y",
+          "@marcelo-ochoa/server-postgres",
+          "${input:pg_url}"
+        ]
+      }
+    }
+  }
+}
+```
+
+## Building
+
+Docker:
+
+```sh
+docker build -t mochoa/mcp-postgres -f src/postgres/Dockerfile .
+```
+
+## License
+
+This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

package/dist/db.js

@@ -0,0 +1,43 @@
+import pg from "pg";
+let pool = undefined;
+let resourceBaseUrl = undefined;
+export async function initializePool(connectionString) {
+    pool = new pg.Pool({
+        connectionString,
+    });
+    // Test connection
+    const client = await pool.connect();
+    client.release();
+    const url = new URL(connectionString);
+    url.protocol = "postgres:";
+    url.password = "";
+    resourceBaseUrl = url;
+}
+export function getPool() {
+    if (!pool) {
+        throw new Error("Postgres connection pool not initialized.");
+    }
+    return pool;
+}
+export function getResourceBaseUrl() {
+    if (!resourceBaseUrl) {
+        throw new Error("Resource Base URL not initialized.");
+    }
+    return resourceBaseUrl;
+}
+export async function withConnection(callback) {
+    const pool = getPool();
+    const client = await pool.connect();
+    try {
+        return await callback(client);
+    }
+    finally {
+        client.release();
+    }
+}
+export async function closePool() {
+    if (pool) {
+        await pool.end();
+        pool = undefined;
+    }
+}

package/dist/handlers.js

@@ -0,0 +1,55 @@
+import { withConnection, getResourceBaseUrl } from "./db.js";
+import { queryHandler } from "./tools/query.js";
+import { statsHandler } from "./tools/stats.js";
+import { connectHandler } from "./tools/connect.js";
+import { explainHandler } from "./tools/explain.js";
+import { awrHandler } from "./tools/awr.js";
+const toolHandlers = {
+    "pg-query": queryHandler,
+    "pg-stats": statsHandler,
+    "pg-explain": explainHandler,
+    "pg-connect": connectHandler,
+    "pg-awr": awrHandler,
+};
+export const callToolHandler = async (request) => {
+    const handler = toolHandlers[request.params.name];
+    if (handler) {
+        return handler(request);
+    }
+    throw new Error(`Unknown tool: ${request.params.name}`);
+};
+const SCHEMA_PATH = "schema";
+export const listResourcesHandler = async (request) => {
+    const resourceBaseUrl = getResourceBaseUrl();
+    return await withConnection(async (client) => {
+        const result = await client.query("SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'");
+        return {
+            resources: result.rows.map((row) => ({
+                uri: new URL(`${row.table_name}/${SCHEMA_PATH}`, resourceBaseUrl).href,
+                mimeType: "application/json",
+                name: `"${row.table_name}" database schema`,
+            })),
+        };
+    });
+};
+export const readResourceHandler = async (request) => {
+    const resourceUrl = new URL(request.params.uri);
+    const pathComponents = resourceUrl.pathname.split("/");
+    const schema = pathComponents.pop();
+    const tableName = pathComponents.pop();
+    if (schema !== SCHEMA_PATH) {
+        throw new Error("Invalid resource URI");
+    }
+    return await withConnection(async (client) => {
+        const result = await client.query("SELECT column_name, data_type FROM information_schema.columns WHERE table_name = $1", [tableName]);
+        return {
+            contents: [
+                {
+                    uri: request.params.uri,
+                    mimeType: "application/json",
+                    text: JSON.stringify(result.rows, null, 2),
+                },
+            ],
+        };
+    });
+};

package/dist/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runServer } from "./server.js";
+runServer().catch(console.error);

package/dist/server.js

@@ -0,0 +1,36 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { initializePool } from "./db.js";
+import { listResourcesHandler, readResourceHandler, callToolHandler } from "./handlers.js";
+import { tools } from "./tools.js";
+const server = new Server({
+    name: "postgres-server",
+    version: "0.6.2",
+}, {
+    capabilities: {
+        resources: {},
+        tools: {},
+    },
+});
+server.setRequestHandler(ListResourcesRequestSchema, listResourcesHandler);
+server.setRequestHandler(ReadResourceRequestSchema, readResourceHandler);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+server.setRequestHandler(CallToolRequestSchema, callToolHandler);
+export async function runServer() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        console.error("Please provide a database URL as a command-line argument");
+        process.exit(1);
+    }
+    const databaseUrl = args[0];
+    try {
+        await initializePool(databaseUrl);
+    }
+    catch (error) {
+        console.error("Failed to initialize database pool:", error);
+        process.exit(1);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/tools/awr.js

@@ -0,0 +1,233 @@
+import { withConnection } from "../db.js";
+export const awrHandler = async (request) => {
+    try {
+        return await withConnection(async (client) => {
+            const report = {
+                timestamp: new Date().toISOString(),
+                database_statistics: {},
+                top_queries: [],
+                table_statistics: [],
+                index_statistics: [],
+                connection_info: {},
+            };
+            // Check if pg_stat_statements extension is available
+            const extCheck = await client.query(`
+                SELECT EXISTS (
+                    SELECT 1 FROM pg_extension WHERE extname = 'pg_stat_statements'
+                ) as has_extension
+            `);
+            const hasPgStatStatements = extCheck.rows[0].has_extension;
+            // 1. Database-wide statistics
+            const dbStats = await client.query(`
+                SELECT 
+                    datname,
+                    numbackends as active_connections,
+                    xact_commit as transactions_committed,
+                    xact_rollback as transactions_rolled_back,
+                    blks_read as blocks_read,
+                    blks_hit as blocks_hit,
+                    CASE 
+                        WHEN (blks_read + blks_hit) > 0 
+                        THEN ROUND(100.0 * blks_hit / (blks_read + blks_hit), 2)
+                        ELSE 0 
+                    END as cache_hit_ratio,
+                    tup_returned as tuples_returned,
+                    tup_fetched as tuples_fetched,
+                    tup_inserted as tuples_inserted,
+                    tup_updated as tuples_updated,
+                    tup_deleted as tuples_deleted,
+                    conflicts,
+                    temp_files,
+                    temp_bytes,
+                    deadlocks,
+                    blk_read_time,
+                    blk_write_time
+                FROM pg_stat_database
+                WHERE datname = current_database()
+            `);
+            report.database_statistics = dbStats.rows[0];
+            // 2. Top queries by total time (if pg_stat_statements is available)
+            if (hasPgStatStatements) {
+                try {
+                    const topQueries = await client.query(`
+                        SELECT 
+                            queryid,
+                            LEFT(query, 100) as query_text,
+                            calls,
+                            ROUND(total_exec_time::numeric, 2) as total_time_ms,
+                            ROUND(mean_exec_time::numeric, 2) as mean_time_ms,
+                            ROUND(min_exec_time::numeric, 2) as min_time_ms,
+                            ROUND(max_exec_time::numeric, 2) as max_time_ms,
+                            ROUND(stddev_exec_time::numeric, 2) as stddev_time_ms,
+                            rows as total_rows,
+                            ROUND((100.0 * shared_blks_hit / NULLIF(shared_blks_hit + shared_blks_read, 0))::numeric, 2) as buffer_hit_ratio,
+                            shared_blks_read,
+                            shared_blks_hit,
+                            shared_blks_dirtied,
+                            shared_blks_written,
+                            temp_blks_read,
+                            temp_blks_written
+                        FROM pg_stat_statements
+                        WHERE dbid = (SELECT oid FROM pg_database WHERE datname = current_database())
+                        ORDER BY total_exec_time DESC
+                        LIMIT 20
+                    `);
+                    report.top_queries = topQueries.rows;
+                }
+                catch (error) {
+                    report.top_queries_note = `pg_stat_statements extension exists but is not properly loaded. Error: ${error.message}. Add 'shared_preload_libraries = pg_stat_statements' to postgresql.conf and restart PostgreSQL.`;
+                }
+            }
+            else {
+                report.top_queries_note = "pg_stat_statements extension not available. Install with: CREATE EXTENSION pg_stat_statements;";
+            }
+            // 3. Table statistics
+            const tableStats = await client.query(`
+                SELECT 
+                    schemaname,
+                    relname as table_name,
+                    seq_scan,
+                    seq_tup_read,
+                    idx_scan,
+                    idx_tup_fetch,
+                    n_tup_ins as inserts,
+                    n_tup_upd as updates,
+                    n_tup_del as deletes,
+                    n_tup_hot_upd as hot_updates,
+                    n_live_tup as live_tuples,
+                    n_dead_tup as dead_tuples,
+                    ROUND(100.0 * n_dead_tup / NULLIF(n_live_tup + n_dead_tup, 0), 2) as dead_tuple_ratio,
+                    last_vacuum,
+                    last_autovacuum,
+                    last_analyze,
+                    last_autoanalyze,
+                    vacuum_count,
+                    autovacuum_count,
+                    analyze_count,
+                    autoanalyze_count
+                FROM pg_stat_user_tables
+                ORDER BY seq_scan + COALESCE(idx_scan, 0) DESC
+                LIMIT 20
+            `);
+            report.table_statistics = tableStats.rows;
+            // 4. Index statistics
+            const indexStats = await client.query(`
+                SELECT 
+                    schemaname,
+                    relname as table_name,
+                    indexrelname as index_name,
+                    idx_scan as index_scans,
+                    idx_tup_read as tuples_read,
+                    idx_tup_fetch as tuples_fetched,
+                    pg_size_pretty(pg_relation_size(indexrelid)) as index_size
+                FROM pg_stat_user_indexes
+                ORDER BY idx_scan DESC
+                LIMIT 20
+            `);
+            report.index_statistics = indexStats.rows;
+            // 5. Connection and activity info
+            const connInfo = await client.query(`
+                SELECT 
+                    COUNT(*) as total_connections,
+                    COUNT(*) FILTER (WHERE state = 'active') as active,
+                    COUNT(*) FILTER (WHERE state = 'idle') as idle,
+                    COUNT(*) FILTER (WHERE state = 'idle in transaction') as idle_in_transaction,
+                    COUNT(*) FILTER (WHERE wait_event_type IS NOT NULL) as waiting,
+                    MAX(EXTRACT(EPOCH FROM (now() - query_start))) as longest_query_seconds,
+                    MAX(EXTRACT(EPOCH FROM (now() - xact_start))) as longest_transaction_seconds
+                FROM pg_stat_activity
+                WHERE datname = current_database()
+            `);
+            report.connection_info = connInfo.rows[0];
+            // 6. Background writer and checkpoint statistics
+            // In PostgreSQL 17+, checkpoint stats moved to pg_stat_checkpointer
+            // and buffer backend stats moved to pg_stat_io
+            const versionResult = await client.query('SHOW server_version_num');
+            const versionNum = parseInt(versionResult.rows[0].server_version_num);
+            if (versionNum >= 170000) {
+                // PostgreSQL 17+: Query multiple views
+                const checkpointerStats = await client.query(`
+                    SELECT 
+                        num_timed as checkpoints_timed,
+                        num_requested as checkpoints_requested,
+                        write_time as checkpoint_write_time,
+                        sync_time as checkpoint_sync_time,
+                        buffers_written as buffers_checkpoint,
+                        stats_reset
+                    FROM pg_stat_checkpointer
+                `);
+                const bgWriterStats = await client.query(`
+                    SELECT 
+                        buffers_clean,
+                        maxwritten_clean,
+                        buffers_alloc
+                    FROM pg_stat_bgwriter
+                `);
+                // Get backend buffer stats from pg_stat_io
+                const ioStats = await client.query(`
+                    SELECT 
+                        SUM(reads) FILTER (WHERE backend_type = 'client backend') as buffers_backend_read,
+                        SUM(writes) FILTER (WHERE backend_type = 'client backend') as buffers_backend_write,
+                        SUM(fsyncs) FILTER (WHERE backend_type = 'client backend') as buffers_backend_fsync
+                    FROM pg_stat_io
+                `);
+                report.bgwriter_statistics = {
+                    ...checkpointerStats.rows[0],
+                    ...bgWriterStats.rows[0],
+                    ...ioStats.rows[0]
+                };
+            }
+            else {
+                // PostgreSQL < 17: Use pg_stat_bgwriter for everything
+                const bgWriterStats = await client.query(`
+                    SELECT 
+                        checkpoints_timed,
+                        checkpoints_req as checkpoints_requested,
+                        checkpoint_write_time,
+                        checkpoint_sync_time,
+                        buffers_checkpoint,
+                        buffers_clean,
+                        maxwritten_clean,
+                        buffers_backend,
+                        buffers_backend_fsync,
+                        buffers_alloc,
+                        stats_reset
+                    FROM pg_stat_bgwriter
+                `);
+                report.bgwriter_statistics = bgWriterStats.rows[0];
+            }
+            // 7. Unused indexes (potential optimization candidates)
+            const unusedIndexes = await client.query(`
+                SELECT 
+                    schemaname,
+                    relname as table_name,
+                    indexrelname as index_name,
+                    idx_scan as scans,
+                    pg_size_pretty(pg_relation_size(indexrelid)) as index_size
+                FROM pg_stat_user_indexes
+                WHERE idx_scan = 0
+                    AND indexrelname NOT LIKE '%_pkey'
+                ORDER BY pg_relation_size(indexrelid) DESC
+                LIMIT 10
+            `);
+            report.unused_indexes = unusedIndexes.rows;
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify(report, null, 2),
+                        mimeType: "application/json"
+                    }],
+                isError: false,
+            };
+        });
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error generating PostgreSQL performance report: ${error?.message ?? error}`
+                }],
+            isError: true,
+        };
+    }
+};

package/dist/tools/connect.js

@@ -0,0 +1,24 @@
+import { initializePool, closePool } from "../db.js";
+export const connectHandler = async (request) => {
+    const connectionString = request.params.arguments?.connectionString;
+    if (typeof connectionString !== "string" || !connectionString) {
+        return {
+            content: [{ type: "text", text: "Missing or invalid connectionString argument." }],
+            isError: true,
+        };
+    }
+    try {
+        await closePool();
+        await initializePool(connectionString);
+        return {
+            content: [{ type: "text", text: `Successfully connected to Postgres DB: ${connectionString}` }],
+            isError: false,
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Failed to connect: ${err}` }],
+            isError: true,
+        };
+    }
+};

package/dist/tools/explain.js

@@ -0,0 +1,13 @@
+import { withConnection } from "../db.js";
+export const explainHandler = async (request) => {
+    const sql = typeof request.params.arguments?.sql === "string"
+        ? request.params.arguments.sql.replace(/;\s*$/, "")
+        : "";
+    return await withConnection(async (client) => {
+        const result = await client.query(`EXPLAIN (ANALYZE, VERBOSE, BUFFERS, FORMAT JSON) ${sql}`);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result.rows[0], null, 2), mimeType: "application/json" }],
+            isError: false,
+        };
+    });
+};

package/dist/tools/query.js

@@ -0,0 +1,25 @@
+import { encode } from "@toon-format/toon";
+import { withConnection } from "../db.js";
+export const queryHandler = async (request) => {
+    const sql = typeof request.params.arguments?.sql === "string"
+        ? request.params.arguments.sql.replace(/;\s*$/, "")
+        : "";
+    return await withConnection(async (client) => {
+        try {
+            await client.query("BEGIN TRANSACTION READ ONLY");
+            const result = await client.query(sql);
+            return {
+                content: [{ type: "text", text: encode(result.rows) }],
+                isError: false,
+            };
+        }
+        catch (error) {
+            throw error;
+        }
+        finally {
+            client
+                .query("ROLLBACK")
+                .catch((error) => console.warn("Could not roll back transaction:", error));
+        }
+    });
+};

package/dist/tools/stats.js

@@ -0,0 +1,54 @@
+import { withConnection } from "../db.js";
+export const statsHandler = async (request) => {
+    const tableName = request.params.arguments?.name;
+    return await withConnection(async (client) => {
+        const result = await client.query(`
+      SELECT json_build_object(
+        'table_stats', (
+          SELECT json_build_object(
+            'schema_name', n.nspname,
+            'table_name', c.relname,
+            'num_rows', c.reltuples,
+            'blocks', c.relpages,
+            'last_analyzed', s.last_analyze
+          )
+          FROM pg_class c
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          LEFT JOIN pg_stat_user_tables s ON s.relid = c.oid
+          WHERE c.relname = $1 AND n.nspname = 'public'
+        ),
+        'index_stats', (
+          SELECT json_agg(
+            json_build_object(
+              'index_name', c2.relname,
+              'num_rows', c2.reltuples,
+              'blocks', c2.relpages,
+              'index_size', pg_size_pretty(pg_relation_size(c2.oid))
+            )
+          )
+          FROM pg_index i
+          JOIN pg_class c ON c.oid = i.indrelid
+          JOIN pg_class c2 ON c2.oid = i.indexrelid
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE c.relname = $1 AND n.nspname = 'public'
+        ),
+        'column_stats', (
+          SELECT json_agg(
+            json_build_object(
+              'column_name', attname,
+              'null_frac', null_frac,
+              'avg_width', avg_width,
+              'n_distinct', n_distinct
+            )
+          )
+          FROM pg_stats
+          WHERE tablename = $1 AND schemaname = 'public'
+        )
+      ) as stats_json
+    `, [tableName]);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result.rows[0].stats_json, null, 2), mimeType: "application/json" }],
+            isError: false,
+        };
+    });
+};

package/dist/tools.js

@@ -0,0 +1,117 @@
+export const tools = [
+    {
+        name: "pg-query",
+        description: "Run a read-only SQL query",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sql: {
+                    type: "string",
+                    description: "The SQL query to execute"
+                },
+                mcp_client: {
+                    "type": "string",
+                    "description": "Specify the name and version of the MCP client implementation being used (e.g. Copilot, Claude, Cline...)",
+                    "default": "UNKNOWN-MCP-CLIENT"
+                },
+                model: {
+                    "type": "string",
+                    "description": "The name (and version) of the language model being used by the MCP client to process requests (e.g. gpt-4.1, claude-sonnet-4, llama4...)",
+                    "default": "UNKNOWN-LLM"
+                }
+            },
+            required: ["sql", "mcp_client", "model"]
+        },
+    },
+    {
+        name: "pg-stats",
+        description: "Get statistics for a specific table",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "The name of the table to get statistics for"
+                },
+                mcp_client: {
+                    "type": "string",
+                    "description": "Specify the name and version of the MCP client implementation being used (e.g. Copilot, Claude, Cline...)",
+                    "default": "UNKNOWN-MCP-CLIENT"
+                },
+                model: {
+                    "type": "string",
+                    "description": "The name (and version) of the language model being used by the MCP client to process requests (e.g. gpt-4.1, claude-sonnet-4, llama4...)",
+                    "default": "UNKNOWN-LLM"
+                }
+            },
+            required: ["name"]
+        },
+    },
+    {
+        name: "pg-explain",
+        description: "Explain Plan for a given SQL query",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sql: {
+                    type: "string",
+                    description: "The SQL query to explain"
+                },
+                mcp_client: {
+                    "type": "string",
+                    "description": "Specify the name and version of the MCP client implementation being used (e.g. Copilot, Claude, Cline...)",
+                    "default": "UNKNOWN-MCP-CLIENT"
+                },
+                model: {
+                    "type": "string",
+                    "description": "The name (and version) of the language model being used by the MCP client to process requests (e.g. gpt-4.1, claude-sonnet-4, llama4...)",
+                    "default": "UNKNOWN-LLM"
+                }
+            },
+            required: ["sql", "mcp_client", "model"]
+        },
+    },
+    {
+        name: "pg-connect",
+        description: "Connect to a PostgreSQL database",
+        inputSchema: {
+            type: "object",
+            properties: {
+                connectionString: {
+                    type: "string",
+                    description: "The PostgreSQL connection string (e.g. postgresql://user:password@host:port/dbname)"
+                },
+                mcp_client: {
+                    "type": "string",
+                    "description": "Specify the name and version of the MCP client implementation being used (e.g. Copilot, Claude, Cline...)",
+                    "default": "UNKNOWN-MCP-CLIENT"
+                },
+                model: {
+                    "type": "string",
+                    "description": "The name (and version) of the language model being used by the MCP client to process requests (e.g. gpt-4.1, claude-sonnet-4, llama4...)",
+                    "default": "UNKNOWN-LLM"
+                }
+            },
+            required: ["connectionString"]
+        },
+    },
+    {
+        name: "pg-awr",
+        description: "Generate a PostgreSQL performance report similar to Oracle AWR. Includes database statistics, top queries (requires pg_stat_statements extension), table/index statistics, connection info, and optimization recommendations.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mcp_client: {
+                    "type": "string",
+                    "description": "Specify the name and version of the MCP client implementation being used (e.g. Copilot, Claude, Cline...)",
+                    "default": "UNKNOWN-MCP-CLIENT"
+                },
+                model: {
+                    "type": "string",
+                    "description": "The name (and version) of the language model being used by the MCP client to process requests (e.g. gpt-4.1, claude-sonnet-4, llama4...)",
+                    "default": "UNKNOWN-LLM"
+                }
+            },
+        },
+    },
+];

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@marcelo-ochoa/server-postgres",
+  "version": "0.6.2",
+  "description": "MCP server for interacting with PostgreSQL databases",
+  "keywords": [
+    "read-only-mcp",
+    "postgres-database",
+    "ai-agent",
+    "llm-tool",
+    "rag"
+  ],
+  "license": "MIT",
+  "author": "Marcelo Fabian Ochoa",
+  "homepage": "https://modelcontextprotocol.io",
+  "bugs": "https://github.com/marcelo-ochoa/servers/issues",
+  "type": "module",
+  "bin": {
+    "mcp-server-postgres": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/*.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.0.1",
+    "@toon-format/toon": "^1.0.0",
+    "pg": "^8.13.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.11.10",
+    "shx": "^0.3.4",
+    "typescript": "^5.6.2"
+  }
+}