Phx DB Explorer MCP Server

A Model Context Protocol (MCP) server that exposes your SQL Server database schema to AI coding assistants (GitHub Copilot, Cursor, etc.). It allows AI tools to discover tables, views, stored procedures, functions, indexes, foreign keys, and more — without writing any SQL themselves.

Prerequisites

Related MCP server: mcp-server-mssql

Project Structure

src/
├── PhxDbExplorer/                  # MCP server application
├── PhxDbExplorer.Tests/            # Unit tests (xUnit, Moq)
└── PhxDbExplorer.IntegrationTests/ # Integration tests (Testcontainers, requires Docker)

Configuration

The server is configured entirely through environment variables.

Example values:

DB_TYPE=mssql
CONNECTION_STRING=Server=localhost,1433;Database=MyDb;User Id=sa;Password=YourPassword;TrustServerCertificate=True;
SCHEMA_FILTER=dbo,hr

Installation

Option A — Download a prebuilt binary (recommended)

Self-contained, single-file executables are published as GitHub Releases for every tagged version — no .NET SDK (or even the .NET runtime) required on the target machine.

1. Go to the Releases page.

2. Download the archive matching your OS/architecture:

   Asset	Platform
   PhxDbExplorer-<version>-win-x64.zip	Windows x64
   PhxDbExplorer-<version>-linux-x64.tar.gz	Linux x64
   PhxDbExplorer-<version>-osx-x64.tar.gz	macOS (Intel)
   PhxDbExplorer-<version>-osx-arm64.tar.gz	macOS (Apple Silicon)

3. Extract it and point your MCP client at the extracted PhxDbExplorer (or PhxDbExplorer.exe) binary.

Each release should have all four assets attached — if one is missing, check the release workflow run for that tag.

Option B — Build from source

Requires the .NET SDK (see Prerequisites above).

dotnet build

Option C — npx (used by the PHR-Foundry Claude Code plugin)

package.json at the repo root wraps Option A behind an npx launcher, so nothing needs to be downloaded or installed by hand:

npx -y github:hsenidBiz/phx-dbexplorer

On first run it downloads the release asset matching your OS/arch into ~/.cache/phx-dbexplorer-mcp/<version>/<rid>/ and execs it; later runs reuse the cached binary. Pin a specific tag with PHX_DBEXPLORER_VERSION=1.2.0 (defaults to the latest release). This is what an MCP client's command should point at instead of a local binary path — see phr-foundry's org-standards plugin for the registered mcpServers entry.

This repo must stay public. The launcher's download step (GET /repos/.../releases/latest and the release asset itself) is unauthenticated — it has no way to use a developer's own git/GitHub credentials — so a private repo would 404 for anyone without direct access, defeating the point of the npx install path.

You still need to set DB_TYPE / CONNECTION_STRING / SCHEMA_FILTER yourself (see Configuration above) — npx only fetches and runs the binary, it doesn't supply your database credentials. In the org-standards plugin these are wired up from PHX_DB_TYPE / PHX_DB_CONNECTION_STRING / PHX_DB_SCHEMA_FILTER in your own shell environment.

Archive extraction on Windows uses a small self-contained zip reader (Node's built-in zlib, no external dependency) rather than shelling out to tar — GNU tar (e.g. the one bundled with Git Bash) can't read .zip at all, and a Windows path's drive-letter colon confuses tar's remote-archive detection regardless. Linux/macOS releases are .tar.gz and still extract via the system tar, which every POSIX machine has.

Registering the Server with an MCP Client

The server is not launched directly. Instead, it is registered in your editor's MCP configuration file so the editor starts and manages it automatically.

VS Code — .vscode/mcp.json

Create (or update) .vscode/mcp.json in your workspace:

{
  "servers": {
    "phx-dbexplorer": {
      "type": "stdio",
      "command": "Path to PhxDbExplorer.exe",
      "args": [],
      "env": {
        "DB_TYPE": "mssql",
        "CONNECTION_STRING": "Server=localhost,1433;Database=YourDatabase;User Id=YourUsername;Password=YourPassword;TrustServerCertificate=True;",
        "SCHEMA_FILTER": "YourSchema"
      }
    }
  }
}

Tip: For a published/built binary, replace the dotnet run command with the path to the compiled executable (e.g. "command": "path/to/PhxDbExplorer.exe").

Once registered, restart your editor and the MCP server will be available to any AI assistant that supports the MCP protocol.

Available MCP Tools

These tools are automatically available to your AI assistant once the server is running.

Running Tests

Unit Tests

No extra dependencies required.

dotnet test src/PhxDbExplorer.Tests

Tests use xUnit, Moq, and FluentAssertions to verify tool behavior and configuration logic in isolation.

Integration Tests

⚠️ Docker is required. Integration tests use Testcontainers to automatically pull and start a SQL Server 2022 container. Docker must be running before executing these tests.

dotnet test src/PhxDbExplorer.IntegrationTests

The container is started automatically at the beginning of the test run and torn down when the tests complete. No manual database setup is needed.

Releasing

Pushing a tag matching v*.*.* (e.g. v1.2.0) triggers the release workflow, which runs the unit tests, publishes self-contained single-file binaries for win-x64, linux-x64, osx-x64, and osx-arm64, and attaches them to a new GitHub Release.

git tag v1.2.0
git push origin v1.2.0

See docs/readme.md for the full CI/CD pipeline documentation, including artifact naming, job breakdown, and pipeline verification history.

Contributing

1. Fork the repository and create a feature branch.

2. Make your changes — keep them focused and well-tested.

3. Ensure all unit tests pass (dotnet test src/PhxDbExplorer.Tests).

4. Open a pull request with a clear description of the change.

Every pull request runs the CI workflow automatically: build, unit tests, and integration tests (Testcontainers spins up its own SQL Server container on the runner — no setup needed on your end).