Database Query Builder MCP Server

Interactive SQL editor with query execution, results table, and database schema exploration.

Features

• Execute SQL Queries - Run arbitrary SQL queries against a PostgreSQL database with real-time results in a structured table view
• Schema Exploration - List all tables in the database with column counts and estimated row statistics
• Table Introspection - View detailed column definitions including data types, nullability, defaults, and primary key constraints
• Auto-Limiting - SELECT queries are automatically limited to 1,000 rows to prevent memory issues
• Execution Metrics - Track query execution time and row counts for performance monitoring
• Safety Features - Statement timeout (30 seconds) prevents long-running queries from hanging

Installation

npm install @gongrzhe/server-db-query-builder

Usage

As a CLI

npx @gongrzhe/server-db-query-builder

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "db-query-builder": {
      "command": "npx",
      "args": ["-y", "@gongrzhe/server-db-query-builder"]
    }
  }
}

Claude Code Configuration

claude mcp add db-query-builder -- npx -y @gongrzhe/server-db-query-builder

Tools

execute-query

Executes a SQL query against the connected PostgreSQL database and returns the results.

Input:

• sql (string): The SQL query to execute

Output:

• columns: Array of column definitions with name and data type
• rows: Array of result rows
• rowCount: Number of rows returned
• executionTimeMs: Query execution time in milliseconds
• wasTruncated: Boolean indicating if results were truncated to 1,000 rows
• error (optional): Error message if query failed

list-tables

Lists all tables in the connected PostgreSQL database with column counts and estimated row counts.

Input: None

Output:

• tables: Array of table objects with:
  • schemaName: Schema name (e.g., "public")
  • tableName: Table name
  • columnCount: Number of columns
  • estimatedRows: Approximate number of rows

describe-table

Returns the column definitions for a specific table, including data types, nullability, defaults, and primary key status.

Input:

• tableName (string): Name of the table to describe
• schemaName (string, optional): Schema name (defaults to "public")

Output:

• schemaName: Schema name
• tableName: Table name
• columns: Array of column definitions with:
  • columnName: Column name
  • dataType: PostgreSQL data type
  • nullable: Boolean indicating if column allows NULL
  • defaultValue: Default value if set, otherwise null
  • isPrimaryKey: Boolean indicating if column is a primary key

Configuration

Set the DATABASE_URL environment variable to connect to a PostgreSQL database:

export DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
npx @gongrzhe/server-db-query-builder

The server will warn if DATABASE_URL is not set, but will start and fail gracefully when queries are attempted.

Example Prompt

Show me all tables in the database and run SELECT * FROM users LIMIT 10

License

MIT