io.github.dataplat/dbatools-mcp-server
MCP server for dbatools β exposes SQL Server management commands as MCP tools
Ask AI about io.github.dataplat/dbatools-mcp-server
Powered by Claude Β· Grounded in docs
I know everything about io.github.dataplat/dbatools-mcp-server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
dbatools-mcp-server
A Model Context Protocol (MCP) server for the dbatools PowerShell module.
Exposes dbatools commands as MCP tools so AI assistants (GitHub Copilot, Claude, etc.) can discover, explain, and execute dbatools commands directly β with all metadata sourced from dbatools' own comment-based help.
Features
list_dbatools_commandsβ search commands by verb, noun, keyword, or risk levelget_dbatools_command_helpβ full normalized help (synopsis, parameters, examples) fromGet-Help -Fullinvoke_dbatools_commandβ execute any dbatools command with safe parameter validation, risk gating, and structured JSON outputcheck_dbatools_environmentβ verify PowerShell + dbatools installation, index freshness, and version alignment- Version mismatch detection β warns when installed dbatools version differs from the indexed version
- Safe mode β non-readonly commands require explicit
confirm: trueto execute - SQL Authentication support β pass
SqlCredential: { username, password }for SQL auth instances
Prerequisites
- Node.js 20+
- PowerShell 7+ (
pwsh) - dbatools PowerShell module
Install-Module dbatools -Scope CurrentUser
Quick Start
# 1. Clone the repo
git clone https://github.com/Dataplat/dbatools-mcp-server.git
cd dbatools-mcp-server
# 2. Install Node dependencies
npm install
# 3. Generate the help index from your local dbatools installation
npm run refresh-help
# 4. Build
npm run build
Then open the folder in VS Code β the .vscode/mcp.json file automatically registers the MCP server.
Connecting to VS Code
The included .vscode/mcp.json registers the server as a local STDIO MCP server.
Open this folder in VS Code and the server will appear in the GitHub Copilot MCP panel.
{
"servers": {
"dbatools": {
"type": "stdio",
"command": "node",
"args": ["${workspaceFolder}/dist/server.js"],
"env": {
"DBATOOLS_SAFE_MODE": "true",
"MAX_OUTPUT_ROWS": "100",
"COMMAND_TIMEOUT_SECONDS": "60"
}
}
}
}
Configuration
All settings are controlled via environment variables (set in .vscode/mcp.json or your shell):
| Variable | Default | Description |
|---|---|---|
PWSH_EXE | pwsh | Path to PowerShell executable |
DBATOOLS_SAFE_MODE | true | When true, non-readonly commands require confirm: true |
MAX_OUTPUT_ROWS | 100 | Maximum rows returned per command execution |
COMMAND_TIMEOUT_SECONDS | 60 | Seconds before PowerShell process is killed |
Refreshing the Help Index
The help index (generated/dbatools-help.json) is generated from your locally installed dbatools module.
Re-run whenever dbatools is updated:
Update-Module dbatools -Scope CurrentUser
npm run refresh-help
The server detects version mismatches at runtime and warns you when the index is stale.
Risk Levels
Commands are automatically classified by verb:
| Risk Level | Verbs | Behavior |
|---|---|---|
readonly | Get, Test, Find, Compare, β¦ | Always allowed |
change | Set, New, Add, Copy, Enable, β¦ | Requires confirm: true in safe mode |
destructive | Remove, Drop, Disable, Reset, β¦ | Requires confirm: true in safe mode |
SQL Authentication
For SQL-auth-only instances (e.g. Docker), pass credentials via the SqlCredential parameter:
{
"SqlInstance": "localhost,1433",
"SqlCredential": { "username": "<SqlLogin>", "password": "YourPassword" }
}
Project Structure
dbatools-mcp-server/
βββ src/
β βββ server.ts # MCP server entry point, tool definitions
β βββ powershell.ts # PowerShell process runner, health checks, version detection
β βββ help-indexer.ts # Help manifest loader and command search
β βββ tool-registry.ts # Risk classification, safe argument builder
β βββ types.ts # Shared TypeScript interfaces
βββ scripts/
β βββ refresh-help.ps1 # Generates generated/dbatools-help.json
βββ generated/ # Help index (gitignored, generated locally)
βββ .vscode/
β βββ mcp.json # VS Code MCP local server registration
βββ dist/ # Compiled output (gitignored)
Contributing
Contributions are welcome! Please open an issue first for significant changes.
This project follows the same community spirit as dbatools.
License
MIT β Β© 2026 DataPlat contributors
