Submit
dhipskind253

mssql-mcp

Community dhipskind253
Updated

mssql-mcp

A read-only Microsoft SQL Server MCP server using connectiondetails from AWS Secrets Manager at tool-call time — nothingis read from disk or environment variables except the secret referenceitself.

Cross-platform: it's a pure-JavaScript MCP server (no native or ODBCdependencies), so it runs identically on macOS, Linux, and Windows vianpx.

Configure in .claude.json

{
  "mcpServers": {
    "my-db": {
      "command": "npx",
      "args": ["-y", "@dhipskind253/mssql-mcp"],
      "env": {
        "AWS_ACCOUNT_ID": "123456789012",
        "SECRET_NAME": "my-aws-secret",
        "AWS_REGION": "us-east-1",
        "TRUST_SERVER_CERTIFICATE": "false"
      }
    }
  }
}
Env var Required Default Description
AWS_ACCOUNT_ID yes — The AWS account where the secret lives. Combined with name + region into a full ARN.
SECRET_NAME yes — The Secrets Manager secret name (no ARN suffix needed).
AWS_REGION yes — AWS region the secret is in (e.g. us-east-1). Also picked up by the AWS SDK as its default region.
TRUST_SERVER_CERTIFICATE no false Skip TLS cert validation to the SQL Server. Accepts true/false/1/0/yes/no. Set true only if you understand why.

Standard AWS SDK env vars (AWS_PROFILE, AWS_ACCESS_KEY_ID, etc.) arehonored via the default credential provider chain. Most users just needaws sso login to be current.

Required secret JSON

The secret value must be a JSON document with at least these fields:

{
  "host": "myserver.database.windows.net",
  "port": 1433,
  "database": "mydb",
  "username": "ro_user",
  "password": "..."
}

database may also be supplied as dbname — the field name AWS usesin its built-in RDS-credentials secret template. If both are present,database wins.

Optional fields (with defaults shown):

Field Default Notes
port 1433
encrypt true TLS to the server.

TLS cert trust is not read from the secret — setTRUST_SERVER_CERTIFICATE in the MCP server's env block instead.Any trustServerCertificate field in the secret JSON is ignored.

Read-only by design

This server cannot insert, update, or delete data. Two layers enforce that:

  1. The run_select tool lexically rejects anything that isn't a singleSELECT or WITH (CTE) statement — including INSERT, UPDATE,DELETE, EXEC, MERGE, DROP, ALTER, SELECT INTO, etc.
  2. No other tool emits write SQL. get_procedure_definition returnsprocedure source — it does not run procedures.

Courtesy note: treat the lexical check as UX, not a securityboundary. As a courtesy to your future self, configure the credentialsyou put in Secrets Manager to be a read-only database login — onewith SELECT and VIEW DEFINITION only. That way an accidental write(or a future bug here) is rejected by SQL Server itself.

Refreshing AWS credentials without restarting

Because the server uses the default AWS credential chain, an expired SSOsession can be recovered without restarting Claude or the MCP server:

  1. Run aws sso login in any terminal.
  2. Ask Claude to call the refresh_secret tool.
  3. Continue working.

If a tool call fails because of AWS auth, the error message will tellyou exactly that and prompt the same flow. Errors are tagged with stableprefixes:

Prefix Meaning
[AWS_AUTH_REQUIRED] SSO session expired or no credentials available.
[AWS_ACCESS_DENIED] Principal lacks secretsmanager:GetSecretValue.
[AWS_SECRET_NOT_FOUND] Secret name / account / region mismatch.
[AWS_SECRET_INVALID] Secret JSON is missing fields or malformed.
[DB_CONNECT_FAILED] Could not reach the SQL Server instance.
[DB_QUERY_FAILED] SQL Server returned an error executing the query.
[INVALID_QUERY] The submitted query violated the read-only rules.

Tools

Tool Purpose
list_schemas User schemas in the database.
list_tables Tables, optionally filtered by schema.
describe_table Columns, types, nullability, identity, PK, defaults.
list_indexes Indexes on a table (one row per index/column).
list_foreign_keys Outgoing FKs from a table.
list_views Views, optionally filtered by schema.
get_view_definition View source SQL.
list_procedures Stored procedures, optionally filtered by schema.
get_procedure_definition Procedure source SQL (does not execute).
sample_rows SELECT TOP n * FROM schema.table (default 10, max 100).
run_select Single SELECT/CTE, capped at max_rows (default 100, hard max 1000).
refresh_secret Re-fetch the secret and reconnect.

Local development

npm install
npm run build
# point your .claude.json command at the local build:
#   "command": "node",
#   "args": ["/absolute/path/to/mssql-mcp/dist/index.js"]

MCP Server · Populars

MCP Server · New