ssms-mcp

A Model Context Protocol (MCP) server that lets AI assistants execute T-SQL queries against Microsoft SQL Server (the engine behind SSMS).

Features

Tools exposed over MCP (stdio):

| Tool | Description | | --- | --- | | execute_query | Run any T-SQL with optional named parameters. | | list_databases | List user databases. | | list_tables | List tables/views in a database (optional schema filter). | | describe_table | Columns, types, nullability, defaults, and PK. | | server_info | Server version + current connection context. |

Safety controls:

• MSSQL_READ_ONLY=true blocks INSERT/UPDATE/DELETE/DDL/EXEC/....
• MSSQL_MAX_ROWS caps rows returned per recordset (default 1000).

Authentication modes (set MSSQL_AUTH_TYPE):

| Value | Description | | --- | --- | | sql | SQL auth (MSSQL_USER / MSSQL_PASSWORD). | | ntlm | Windows / NTLM (MSSQL_DOMAIN / MSSQL_NTLM_USER / MSSQL_NTLM_PASSWORD). | | entra-interactive | Microsoft Entra MFA via browser popup — same flow SSMS uses. | | entra-device-code | Microsoft Entra MFA via device-code flow (great for headless / remote shells). | | entra-default | DefaultAzureCredential chain (Azure CLI, VS, env vars, MSI…). | | entra-password | Entra username + password. Does NOT support MFA. | | entra-service-principal | App registration client credentials. | | entra-msi | Managed Identity (Azure VMs, App Service, etc.). | | entra-access-token | Pre-supplied bearer token in MSSQL_ACCESS_TOKEN. |

Default: sql if MSSQL_USER is set, otherwise ntlm if MSSQL_DOMAIN is set, otherwise entra-default.

Install

npm install -g ssms-mcp

Or run with npx (no install):

npx ssms-mcp

Configure

Set environment variables before launching:

| Variable | Required | Default | Notes | | --- | --- | --- | --- | | MSSQL_SERVER | yes | — | localhost, host\SQLEXPRESS, FQDN, etc. | | MSSQL_DATABASE | no | — | Default database. | | MSSQL_USER | no | — | SQL auth user. Omit for Windows auth. | | MSSQL_PASSWORD | no | — | SQL auth password. | | MSSQL_PORT | no | 1433 | | | MSSQL_INSTANCE_NAME | no | — | e.g. SQLEXPRESS. | | MSSQL_ENCRYPT | no | true | | | MSSQL_TRUST_SERVER_CERTIFICATE | no | true | Set false in production. | | MSSQL_CONNECT_TIMEOUT_MS | no | 15000 | | | MSSQL_REQUEST_TIMEOUT_MS | no | 30000 | | | MSSQL_READ_ONLY | no | false | Block writes/DDL. | | MSSQL_MAX_ROWS | no | 1000 | Per recordset cap. | | MSSQL_AUTH_TYPE | no | auto | See table above. | | MSSQL_TENANT_ID | optional* | — | Azure AD tenant id (or common / organizations). See note below. | | MSSQL_CLIENT_ID | optional | Azure CLI public client | App registration client id. | | MSSQL_REDIRECT_URI | entra-interactive | http://localhost | Must match app reg. | | MSSQL_ENTRA_USERNAME | optional | — | Login hint / username for entra-password. | | MSSQL_ENTRA_PASSWORD | entra-password | — | Password (no MFA). | | MSSQL_CLIENT_SECRET | entra-service-principal | — | App reg secret. | | MSSQL_ACCESS_TOKEN | entra-access-token | — | Bearer token for https://database.windows.net. | | MSSQL_DOMAIN / MSSQL_NTLM_USER / MSSQL_NTLM_PASSWORD | ntlm | — | NTLM auth. |

* MSSQL_TENANT_ID is only required for entra-password and entra-service-principal. For entra-interactive, entra-device-code, and entra-default it can be omitted — @azure/identity will default to the organizations tenant, which works for any work/school account in its home tenant. Set it explicitly when:

• you are a guest in the target Azure SQL tenant, or
• you want to skip the account picker / pin auth to a specific tenant.

Use with VS Code / Claude Desktop

Add to your MCP client config (e.g. claude_desktop_config.json or VS Code MCP settings):

{
  "mcpServers": {
    "ssms": {
      "command": "npx",
      "args": ["-y", "ssms-mcp"],
      "env": {
        "MSSQL_SERVER": "localhost",
        "MSSQL_DATABASE": "AdventureWorks",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "your-password",
        "MSSQL_READ_ONLY": "true"
      }
    }
  }
}

Azure SQL with Microsoft Entra MFA (browser popup)

This matches SSMS → "Microsoft Entra MFA". On first use, a browser window opens and you complete MFA; the token is cached in-memory until it expires.

{
  "mcpServers": {
    "ssms": {
      "command": "npx",
      "args": ["-y", "ssms-mcp"],
      "env": {
        "MSSQL_SERVER": "myserver.database.windows.net",
        "MSSQL_DATABASE": "mydb",
        "MSSQL_AUTH_TYPE": "entra-interactive",
        "MSSQL_TENANT_ID": "<your-tenant-id-or-common>",
        "MSSQL_ENTRA_USERNAME": "[email protected]",
        "MSSQL_READ_ONLY": "true"
      }
    }
  }
}

Headless / remote machine? Use device code flow — the URL + code are printed to stderr:

"env": {
  "MSSQL_SERVER": "myserver.database.windows.net",
  "MSSQL_DATABASE": "mydb",
  "MSSQL_AUTH_TYPE": "entra-device-code",
  "MSSQL_TENANT_ID": "<tenant>"
}

Already signed in via az login / Visual Studio? Just use the default chain:

"env": {
  "MSSQL_SERVER": "myserver.database.windows.net",
  "MSSQL_DATABASE": "mydb",
  "MSSQL_AUTH_TYPE": "entra-default"
}

Example tool calls

// execute_query
{
  "query": "SELECT TOP (@n) name FROM sys.tables WHERE name LIKE @pattern",
  "parameters": { "n": 5, "pattern": "Sales%" }
}

// describe_table
{ "table": "dbo.Customer", "database": "Sales" }

Develop

npm install
npm run build
npm start

License

MIT