sql-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| SQL_MCP_AUTH | No | Authentication mode: 'sql' or 'windows'. Defaults to 'sql' when a user is set, otherwise 'windows'. | sql if SQL_MCP_USER is set, otherwise windows |
| SQL_MCP_NAME | No | Name of the environment-based profile. | default |
| SQL_MCP_PORT | No | Separate port for the SQL Server. | |
| SQL_MCP_USER | No | SQL login username (used for SQL authentication). | |
| SQL_MCP_EXTRA | No | Raw connection string additions, e.g. 'MultiSubnetFailover=yes;ApplicationIntent=ReadOnly'. | |
| SQL_MCP_CONFIG | No | Path to a multi-profile JSON configuration file (e.g. connections.json) for defining multiple named connections. | |
| SQL_MCP_DRIVER | No | Driver selection: 'auto', 'pyodbc', or 'mssql-python'. | auto |
| SQL_MCP_SERVER | No | SQL Server address; host, host\INSTANCE, or host,port. Required for single-profile environment configuration. | |
| SQL_MCP_ENCRYPT | No | Encryption mode: 'yes', 'no', or 'strict'. | yes |
| SQL_MCP_APP_NAME | No | Application name shown in sys.dm_exec_sessions.program_name. | sql-mcp |
| SQL_MCP_DATABASE | No | Initial database to connect to. | master |
| SQL_MCP_MAX_ROWS | No | Maximum rows returned per result set. | 1000 |
| SQL_MCP_PASSWORD | No | SQL login password (used for SQL authentication). | |
| SQL_MCP_READONLY | No | When true, blocks write commands (INSERT/UPDATE/DELETE/DDL, EXEC, BACKUP, KILL, job changes, etc.). | false |
| SQL_MCP_ODBC_DRIVER | No | Explicit ODBC driver name, e.g. 'ODBC Driver 17 for SQL Server'. | newest available |
| SQL_MCP_LOGIN_TIMEOUT | No | Login timeout in seconds. | 15 |
| SQL_MCP_QUERY_TIMEOUT | No | Query timeout in seconds (0 = unlimited); can be overridden per tool call with timeout_seconds. | 300 |
| SQL_MCP_TRUST_SERVER_CERTIFICATE | No | Trust the server certificate (useful for internal self-signed certificates). | true |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Microsoft SQL Server (2017+) tools. Every tool takes an optional connection (profile name, see
list_connections) - omit it to use the default profile. Connections are persistent, so temp tables,
SET options and open transactions survive between calls on the same connection.
execute_sql runs any T-SQL (SELECT/DML/DDL/admin). Scripts may contain GO separators. Use
paramswith ? placeholders for values instead of string concatenation.For CREATE/ALTER PROCEDURE/VIEW/FUNCTION/TRIGGER put the CREATE in its own batch (GO before/after).
Results come back as JSON: result_sets[{columns, rows}], rows_affected, messages, errors.
Wrap risky multi-statement changes in begin_transaction ... commit_transaction / rollback_transaction.
SQL Server Agent jobs: list_jobs, get_job, create_job, update_job, delete_job, start_job, stop_job, add/update/delete_job_step, add/delete_job_schedule, get_job_history, list_running_jobs.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_connectionsA | List configured SQL Server connection profiles (passwords are never shown). |
| add_connectionB | Register (or replace) a connection profile at runtime and test it. auth: 'windows' = the current Windows logon (integrated/trusted), 'sql' = SQL login (user + password). Prefer password_env (name of an environment variable) over passing a password in chat. server: 'host', 'host\INSTANCE' or 'host,port'. |
| remove_connectionC | Close and forget a connection profile. |
| test_connectionB | Connect and return server/version/login info (SQL 2017/2019/2022 ...), auth scheme and Agent status. |
| execute_sqlA | Execute any T-SQL: SELECT, INSERT/UPDATE/DELETE/MERGE, DDL (CREATE/ALTER/DROP), EXEC, DBCC, BACKUP, ...
|
| execute_procedureB | Execute a stored procedure with named (or positional) parameters and capture OUTPUT params + return value. procedure: 'dbo.MyProc' or '[db].[schema].[proc]'. params: {"CustomerId": 5, "Name": "x"} (the @ is optional) or a positional list. output_params: {"Total": "decimal(18,2)", "Msg": "nvarchar(4000)"} - a key also present in params is INPUT/OUTPUT. |
| begin_transactionA | BEGIN TRANSACTION on the persistent connection. Later execute_sql calls run inside it until commit/rollback. isolation_level (optional): READ UNCOMMITTED | READ COMMITTED | REPEATABLE READ | SNAPSHOT | SERIALIZABLE. |
| commit_transactionB | COMMIT all open transactions on the connection. |
| rollback_transactionB | ROLLBACK the open transaction on the connection (no-op when none is open). |
| transaction_statusA | Show @@TRANCOUNT, XACT_STATE() and isolation level of the connection. |
| list_databasesB | List databases with state, recovery model, compatibility level and size (MB). |
| list_objectsB | List user objects. object_type: table|view|procedure|function|trigger|synonym|sequence (omit = all). name_like uses LIKE syntax, e.g. 'Customer%'. |
| describe_tableB | Columns (type, nullability, identity, default, computed), primary key, indexes, foreign keys and row count of a table or view. table: 'dbo.Customers' or 'Customers'. |
| get_object_definitionB | Return the T-SQL source of a procedure, view, function or trigger (like sp_helptext, but complete). |
| list_jobsB | List SQL Server Agent jobs with enabled flag, running state, last outcome and next run time. |
| get_jobB | Job details: properties, steps (with commands) and schedules. |
| create_jobA | Create an Agent job with steps and optional schedules in ONE transaction (all or nothing). steps: [{"name": "Step 1", "command": "EXEC dbo.DoWork", "database": "MyDb", "subsystem": "TSQL" (default) | "CmdExec" | "PowerShell" | "SSIS", "on_success": "next"|"quit_success"|"quit_failure"|"goto:2", "on_fail": ..., "retry_attempts": 0, "retry_interval": 0, "output_file": null, "raw": {any extra sp_add_jobstep parameter}}] schedules: [{"name": "Nightly", "type": "daily"|"weekly"|"monthly"|"once"|"agent_start"|"idle", "start_time": "02:30", "every_n": 1, "days": ["mon","fri"] (weekly), "day_of_month": 1 (monthly), "repeat_every_minutes": 15 | "repeat_every_hours": 1 | "repeat_every_seconds": 30, "end_time": "23:59", "start_date": "2026-01-31", "end_date": ..., "enabled": true, "raw": {extra sp_add_jobschedule params}}] Default on_success: 'next' for every step except the last ('quit_success'). |
| update_jobC | Rename / enable / disable / change description, category, owner or start step of a job. |
| delete_jobB | Delete an Agent job (and by default its history). |
| start_jobA | Start a job asynchronously (optionally from a given step). Check progress with list_running_jobs / get_job_history. |
| stop_jobC | Stop a running job. |
| add_job_stepA | Add a step to an existing job. Same step fields as create_job; set "step_id" to insert at a position. |
| update_job_stepC | Change fields of a job step (name, command, database, subsystem, on_success, on_fail, retries, ...). |
| delete_job_stepA | Delete one job step (step_id from get_job). |
| add_job_scheduleC | Attach a new schedule to a job. Same schedule fields as create_job. |
| delete_job_scheduleA | Detach a schedule from a job (and delete it if no other job uses it). |
| get_job_historyC | Recent job/step executions with status, duration and messages (newest first). |
| list_running_jobsB | Jobs currently executing, with elapsed time and current step. |
| list_sessionsC | Server sessions with login, host, program, database, status, blocking session, wait, CPU and current SQL. |
| kill_sessionA | KILL a server session (requires ALTER ANY CONNECTION). Cannot kill this tool's own session. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 30 tools
Each tool targets a distinct resource+action: connection management, query execution (execute_sql vs execute_procedure clearly separated), transaction control, metadata inspection, Agent jobs, and sessions. A few pairs have subtle overlap (list_jobs vs list_running_jobs, get_job vs get_job_history, update_job vs update_job_step), but descriptions sharpen the boundaries well.
Almost entirely consistent verb_noun snake_case (list_connections, add_connection, create_job, delete_job_step, get_job_history, kill_session). The only deviation is transaction_status, which is noun-first, a minor blip in an otherwise predictable scheme.
30 tools is heavy; the Agent-job surface alone consumes 14 tools (CRUD for jobs, steps, schedules, history, running). Each tool does something distinct, but the set is large enough that scope feels sprawling rather than tightly earned.
Broad and well-rounded: connection CRUD, arbitrary T-SQL, procedure execution, full transaction lifecycle, metadata (databases/objects/describe_table/definitions), full Agent job lifecycle, and session monitoring. Minor gaps exist (no dedicated query-plan/EXPLAIN, no user/permission or index-management helpers), but execute_sql can cover most of these.