mcp-sql

CLI tool / MCP server for connecting to SQL Server via the Model Context Protocol.

Propiedad de Isasoft SAS.

Install dependencies

bun install

Development

Run directly with Bun (dev mode):

bun run src/cli.ts --help

Building a standalone executable

Compile to a single native executable with no Bun/Node runtime required on the target machine:

bun run build:win        # dist/mcp-sql-win-x64.exe (Windows x64)

Cross-compile scripts are also available (not run/verified as part of this build, except build:linux which was successfully cross-compiled on Windows; build:mac-x64 / build:mac-arm64 have not been verified on real macOS hardware):

bun run build:mac-x64    # dist/mcp-sql-macos-x64 (macOS Intel, cross-compiled, unverified)
bun run build:mac-arm64  # dist/mcp-sql-macos-arm64 (macOS Apple Silicon, cross-compiled, unverified)
bun run build:linux      # dist/mcp-sql-linux-x64 (Linux x64, cross-compiled)

Output binaries are written to dist/.

Usage

Once built (or via bun run src/cli.ts in dev mode), the CLI exposes these subcommands:

mcp-sql setup [name]  Interactively configure a SQL Server connection
                       (defaults to the name "default")
mcp-sql list           List configured connections and mark the active one
mcp-sql use <name>     Switch which configured connection is active
mcp-sql remove <name>  Remove a configured connection (and its credential)
mcp-sql run            Run mcp-sql in server mode (starts the MCP server)
mcp-sql discover        Detect installed AI clients (Claude Desktop, Cline, Roo
                        Code) and configure them to use mcp-sql

Multiple connections

mcp-sql can store more than one named SQL Server connection at a time, but only one is active at any given moment — that's the one mcp-sql run (and therefore any connected AI client) uses. If you never pass an explicit name, everything behaves exactly as before under the name "default".

setup

mcp-sql setup          # configure (or reconfigure) the "default" connection
mcp-sql setup staging  # configure a connection named "staging"

Walks you through an interactive wizard to configure and store the SQL Server connection details/credentials under the given name (default if omitted). At the end it asks whether this connection should become the active one (defaults to "yes" if it's the first connection you've ever configured).

list

mcp-sql list

Lists the names of all configured connections along with their host and database (never the password), marking which one is active. Prints a clean message (no crash) if none are configured yet.

use

mcp-sql use staging

Marks the given connection as active. If the name doesn't exist, prints a clear error along with the list of known connection names.

remove

mcp-sql remove staging

Removes a configured connection along with its stored credential. Refuses to remove the currently active connection — switch to another one first with mcp-sql use <other-name>.

discover

mcp-sql discover           # detect clients and write/merge their MCP config
mcp-sql discover --dry-run # preview what would be written, without touching any files

Detects installed AI clients (Claude Desktop, Cline, Roo Code) and injects an mcp-sql entry into each client's MCP config file, pointing at this executable's own path (command) with args: ["run"]. Existing config content and other MCP server entries are preserved; a .bak backup of the previous file is written on every real (non-dry-run) injection.

run

mcp-sql run

Starts mcp-sql in MCP server mode. This is what AI clients invoke — you normally don't run this manually; discover wires it up for you.

Permanent install location

discover injects the absolute path of the currently running executable (process.execPath) into each client's config. That means the compiled .exe must stay put once you've run discover against it — if you move or rename it afterward, the client configs will point at a file that no longer exists there.

Recommended: leave the compiled executable at

C:\Users\Wil\appisoft\mcp\dist\mcp-sql-win-x64.exe

which is where bun run build:win produces it, inside this stable project directory.

Do not move this file after running discover. If you do need to move it, re-run discover from the executable's new location afterward (e.g. path\to\new\location\mcp-sql-win-x64.exe discover) to update the client configs to match.

Instalación / Distribución

Releases are built automatically by the Azure Pipelines pipeline defined in azure-pipelines.yml:

1. Push a tag matching v* (e.g. v1.0.0). The pipeline triggers on tag push (or can be run manually), installs Bun, runs bun test and bunx tsc --noEmit as hard gates, then runs all 4 bun run build:* scripts on a single windows-latest agent (Bun cross-compiles the mac/linux targets from Windows; only build:win and build:linux have been run-verified so far — the mac builds are best-effort/unverified on real hardware, see the note above).

2. SHA256 checksums for all 4 binaries are generated into dist/checksums.sha256.

3. Everything (the 4 binaries, the install scripts, and the checksums file) is published as an Azure DevOps pipeline artifact named mcp-sql-release. Download it from the pipeline run's "Artifacts" tab. (A commented-out GitHubRelease@1 block in the pipeline shows how to also publish to a GitHub Release once a GitHub service connection is configured.)

End users then install with a single script from inside the downloaded mcp-sql-release folder:

# Windows
.\install.ps1

# macOS / Linux
./install.sh

Both scripts install the binary, optionally run mcp-sql setup (interactive credential wizard) and mcp-sql discover (configures Claude Desktop, Cline, Roo Code), and print clearly what they're about to do before touching any other application's config files. Pass -SkipSetup/-SkipDiscover (PowerShell) or --skip-setup/--skip-discover (bash) to opt out of the automatic steps.

La carpeta /docs de este repo está lista para publicarse como la Wiki del proyecto en Azure DevOps (Project Settings -> Wikis -> Publish code as wiki -> este repo -> /docs). Incluye una guía de instalación estilo "one-liner" (adaptada para el feed privado de Azure Artifacts) — ver docs/Installation.md.

Alternativamente (o además), una vez que este repo viva en GitHub, la misma carpeta /docs se puede publicar con GitHub Pages: habilita Settings -> Pages -> Source: "GitHub Actions" (una sola vez), y el workflow .github/workflows/pages.yml construye y despliega docs/ automáticamente (vía Jekyll) en cada push a main que toque docs/**.

Attribution

"Propiedad de Isasoft SAS" is printed as part of mcp-sql --help output.