sql-server-analyst-mcp

SQL Server Analyst MCP

Read-only SQL Server analyst for AI tools — safe schema exploration, stored procedure explanation, dependency mapping, permission analysis, and performance guidance.

Built for developers, DBAs, and support engineers who need an AI assistant that understands SQL Server databases deeply and safely.

What it does

• Schema exploration — list databases, schemas, tables, views, procedures, and functions
• Object description — full metadata: columns, types, keys, constraints, indexes, and definition excerpts
• Stored procedure explanation — plain-language analysis of purpose, parameters, referenced objects, and risky patterns
• Dependency mapping — upstream/downstream impact analysis for any database object
• Permission analysis — users, roles, memberships, and object-level grants
• Safe query execution — SELECT-only with enforced row limits and timeout controls
• SQL risk analysis — static analysis of SQL text for dangerous or inefficient patterns
• Table statistics — row counts, sizes, index coverage, and storage details

All operations are strictly read-only. Data modification is not possible.

Quick start

1. Install dependencies

npm install
npm run build

2. Configure environment

cp .env.example .env
# Edit .env with your SQL Server credentials

Minimum required .env:

MSSQL_SERVER=localhost
MSSQL_USER=sa
MSSQL_PASSWORD=your_password
MSSQL_DATABASE=YourDatabase
MSSQL_TRUST_SERVER_CERT=true   # for local dev only

3. Add to your MCP client

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "sql-server-analyst": {
      "command": "node",
      "args": ["C:/path/to/sql-server-analyst-mcp/dist/index.js"],
      "env": {
        "MSSQL_SERVER": "localhost",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_DATABASE": "YourDatabase",
        "MSSQL_TRUST_SERVER_CERT": "true"
      }
    }
  }
}

VS Code / Cursor (.mcp.json)

{
  "servers": {
    "sql-server-analyst": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "MSSQL_SERVER": "localhost",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_DATABASE": "YourDatabase",
        "MSSQL_TRUST_SERVER_CERT": "true"
      }
    }
  }
}

Available tools

Tool	Description
ping	Test connection, return server version and capabilities
list_databases	List accessible databases
list_schemas	List schemas with object counts
search_objects	Find tables, views, procedures, and functions by keyword
describe_object	Full metadata for any database object
inspect_schema_summary	Compact domain overview of a database or schema
execute_safe_query	Run a SELECT query with enforced limits
explain_stored_procedure	Plain-language explanation of a procedure or function
get_dependency_map	Upstream and downstream dependency map for change impact
analyze_permissions	Users, roles, memberships, and object grants
analyze_sql_risks	Static risk analysis of SQL text or a named object
get_table_stats	Row counts, sizes, indexes, and constraints for a table

Minimum SQL Server permissions

The login used by this server requires only:

-- Grant VIEW DEFINITION to inspect object definitions
GRANT VIEW DEFINITION TO [your_login];

-- Grant SELECT on the schema(s) you want to expose
GRANT SELECT ON SCHEMA::dbo TO [your_login];

-- For row count and size data
GRANT VIEW DATABASE STATE TO [your_login];

No sysadmin, db_owner, or write permissions are needed or wanted.

Security model

• Read-only by design — INSERT, UPDATE, DELETE, MERGE, DDL, and EXEC are blocked at the server layer
• Deny-list enforcement — dangerous patterns (xp_cmdshell, OPENROWSET, BULK INSERT, etc.) are blocked before execution
• Row limits — all query execution enforces a configurable row cap (default: 100, max: 1000)
• Query timeouts — all queries have a server-enforced timeout (default: 30 seconds)
• Object name validation — all internally generated queries use bracket-escaped, validated identifiers
• Secret redaction — passwords and credentials are never included in logs or error messages

See docs/security.md for the full security model.

Development

npm run build        # Compile TypeScript
npm run typecheck    # Type check without emitting
npm test             # Run unit tests
npm run test:watch   # Watch mode
npm run dev          # Watch + run (requires built dist/)

See docs/setup.md for the full development guide.

Supported SQL Server versions

SQL Server 2016 and later. Earlier versions may lack some system catalog views used for dependency tracking.

Roadmap

• V1.5 — Query Store integration, object comparison across environments, Windows/integrated auth, Docker packaging
• V2 — Remote streamable HTTP transport, team/shared features, self-hosted enterprise packaging

License

MIT