mcp-sql

CLI tool / MCP server for connecting to SQL Server or MySQL 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 or MySQL 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
mcp-sql --web           Open a local web UI to manage connections (also
                        available as `mcp-sql run --web`); binds to
                        127.0.0.1 only, same-machine access only

Multiple connections

mcp-sql can store more than one named connection at a time (SQL Server, MySQL, or a mix of both), 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 connection details/credentials under the given name (default if omitted). The first question is which database engine to use: SQL Server or MySQL. The rest of the wizard adapts to that choice — the default port becomes 1433 (SQL Server) or 3306 (MySQL), and the encryption prompts differ: SQL Server asks "Encrypt the connection?" / "Trust server certificate?", while MySQL asks a single "Use SSL for the connection?". 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 GitHub Actions workflow defined in .github/workflows/release.yml:

1. Push a tag matching v* (e.g. v1.0.0). The workflow triggers on tag push (or can be run manually via workflow_dispatch), installs Bun (oven-sh/setup-bun), runs bun test and bunx tsc --noEmit as hard gates, patches package.json's version to match the tag, then runs all 4 bun run build:* scripts on a single windows-latest runner (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 a GitHub Release using the built-in GITHUB_TOKEN — no PAT or external service connection needed.

End users then install with a single one-liner (see docs/Installation.md for the exact commands), or by downloading the release assets and running the install script manually:

# 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 se publica como sitio 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.