Database Explorer MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to explore and query PostgreSQL databases. Built with .NET 10 and featuring a Zoo-themed demo schema with Entity Framework Core.

Overview

This MCP server exposes three primary tools for database interaction:

• list_tables - Lists all user tables in the public schema
• describe_table - Shows column definitions, types, and constraints for a specific table
• read_query - Executes read-only SQL queries (SELECT, WITH, EXPLAIN)

The server uses stdio transport, making it compatible with Claude Desktop, MCP Inspector, and other MCP clients.

Features

• Read-only database access with built-in query validation
• Parameterized queries to prevent SQL injection
• Entity Framework Core integration for schema management
• Zoo-themed demo data with complex relationships:
  • Table-Per-Hierarchy (TPH) inheritance for Animals
  • One-to-One relationships (Animal to MedicalRecord)
  • One-to-Many relationships (Zoo to Enclosure to Animal)
  • Many-to-Many relationships (Animal to Keeper)
• CLI modes for database migration and seeding
• Full MCP protocol compliance with JSON-RPC over stdio

Prerequisites

• .NET 10 SDK
• Docker Desktop
• Node.js (optional, for MCP Inspector)

Installation

1. Clone the Repository

git clone https://github.com/YOUR_USERNAME/mcp-db-explorer.git
cd mcp-db-explorer

2. Start PostgreSQL

docker compose up -d

This starts PostgreSQL 16 on port 5433 with the following credentials:

• Database: mcpdb
• Username: mcpuser
• Password: mcppassword

3. Run Migrations and Seed Data

# Apply database schema
dotnet run --project DbExplorerMcp -- --migrate

# Populate with sample Zoo data
dotnet run --project DbExplorerMcp -- --seed

4. Build the Project

dotnet build McpPgProject.slnx

Usage

Running as MCP Server

dotnet run --project DbExplorerMcp

The server listens on stdin/stdout for JSON-RPC messages. This mode is intended for use by MCP clients, not direct terminal interaction.

Testing with MCP Inspector

npx @modelcontextprotocol/inspector dotnet run --project DbExplorerMcp

Opens a web interface at http://localhost:6274 where you can:

• View available tools
• Test tool invocations
• Inspect JSON-RPC messages
• Debug server responses

Connecting to Claude Desktop

Add the following to your Claude Desktop config file:

Location: %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "db-explorer": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "C:\\path\\to\\mcp-db-explorer\\DbExplorerMcp\\DbExplorerMcp.csproj"
      ]
    }
  }
}

Restart Claude Desktop. You can now ask Claude to query your database:

"List all tables in the database"
"Describe the Animals table"
"Show me all mammals in the zoo"

Architecture

Project Structure

FirstMcp/
├── DbExplorerMcp/
│   ├── Data/
│   │   ├── ZooDbContext.cs       # EF Core DbContext
│   │   └── ZooSeeder.cs          # Sample data generation
│   ├── Models/
│   │   ├── Animal.cs             # TPH inheritance (Mammal, Bird, Reptile)
│   │   ├── Zoo.cs
│   │   ├── Enclosure.cs
│   │   ├── MedicalRecord.cs
│   │   └── Keeper.cs
│   ├── Tools/
│   │   └── DatabaseTools.cs      # MCP tool definitions
│   ├── Migrations/               # EF Core migrations
│   └── Program.cs                # Application entry point
├── docker-compose.yml            # PostgreSQL container config
├── init.sql                      # Initial database setup
└── README.md

MCP Tools

list_tables

Lists all user-defined tables in the public schema.

**

... View full README on GitHub