ddonathan/mssql-mcp-server

MSSQL MCP Server

Model Context Protocol (MCP) server for Microsoft SQL Server with SQL authentication.

Features

• Full SQL Support: Execute SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, and more
• Automatic .env Loading: Loads database credentials from your project's .env file
• Cross-Database Queries: Query multiple databases on the same server
• Schema Exploration: List tables, views, procedures, and describe table structures
• Connection Pooling: Efficient connection management with configurable pool settings
• Zod Validation: Runtime input validation for all tool parameters
• Multiple Response Formats: Choose between JSON and Markdown output
• Row Limiting: Automatic pagination with configurable maxRows parameter
• Actionable Error Messages: Clear error messages with troubleshooting suggestions

Installation

Install directly from GitHub:

npm install github:ddonathan/mssql-mcp-server

Or with pnpm:

pnpm add github:ddonathan/mssql-mcp-server

Configuration

1. Add to your .env file:

DB_SERVER=your-server.com
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password
DB_PORT=1433
DB_TRUST_CERT=true
DB_ENCRYPT=false

2. Configure in .claude/.mcp.json:

{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": [
        "./node_modules/mssql-mcp-server/dist/index.js"
      ],
      "env": {}
    }
  }
}

The server automatically loads credentials from your project's .env file based on the current working directory.

Available Tools

query

Execute any SQL statement and return results or status.

Parameters:

• sql (string, required): The SQL statement to execute
• maxRows (number, optional): Maximum rows to return for SELECT queries (default: 1000, max: 10000)
• response_format (string, optional): Output format - "json" (default) or "markdown"

Examples:

-- SELECT query (returns data)
SELECT * FROM users WHERE status = 'active'

-- With row limit
{ "sql": "SELECT * FROM large_table", "maxRows": 100 }

-- Markdown format for readability
{ "sql": "SELECT TOP 10 * FROM Customers", "response_format": "markdown" }

-- CREATE VIEW (returns success message)
CREATE VIEW migration.MyView AS SELECT id, name FROM users

-- INSERT (returns rows affected)
INSERT INTO users (name, email) VALUES ('John', 'john@example.com')

-- Cross-database query
SELECT * FROM other_database.dbo.table1

list_tables

List all tables and views in the database.

Parameters:

• schema (string, optional): Filter by schema name (e.g., "dbo")
• response_format (string, optional): Output format - "json" (default) or "markdown"

Examples:

// List all tables
{}

// Filter by schema
{ "schema": "dbo" }

// Human-readable format
{ "response_format": "markdown" }

describe_table

Get detailed schema information for a specific table including columns, data types, nullability, and defaults.

Parameters:

• table (string, required): Table name (can include schema like "dbo.MyTable")
• response_format (string, optional): Output format - "json" (default) or "markdown"

Examples:

{ "table": "Customers" }
{ "table": "dbo.Candidates" }
{ "table": "sales.Orders", "response_format": "markdown" }

get_database_stats

Get database statistics including size, table counts, and SQL Server version info.

Parameters:

• response_format (string, optional): Output format - "json" (default) or "markdown"

Returns:

• Server name and database name
• Current user
• SQL Server version
• Table and view counts
• Database size (if permissions allow)

list_procedures

List all stored procedures in the database.

Parameters:

• schema (string, optional): Filter by schema name
• response_format (string, optional): Output format - "json" (default) or "markdown"

connection_health

Check database connection health and return diagnostic information.

Returns:

• Connection status (healthy/unhealthy)
• Response latency in milliseconds
• Server name and time
• Pool status

Response Formats

JSON Format (default)

SELECT queries:

[
  {"id": 1, "name": "John"},
  {"id": 2, "name": "Jane"}
]

DDL/DML operations:

{
  "success": true,
  "rowsAffected": [1],
  "message": "Query executed successfully. Rows affected: 1"
}

Markdown Format

SELECT queries:

# Query Results

*2 rows returned*

| id | name |
| --- | --- |
| 1 | John |
| 2 | Jane |

Tables list:

# Tables

*15 tables found*

## Schema: dbo

- `Customers`
- `Orders`
- `Products` *(view)*

Error Handling

The server provides actionable error messages for common issues:

Version History

v2.0.0

• Breaking: Migrated to modern MCP SDK with McpServer class
• Added Zod validation for all input parameters
• Added maxRows parameter for query pagination
• Added response_format parameter (json/markdown) to all tools
• Added schema filter to list_tables
• Added new tools: get_database_stats, list_procedures, connection_health
• Improved error messages with actionable troubleshooting suggestions
• Updated to @modelcontextprotocol/sdk v1.6.1

v1.1.0

• Added support for DDL operations (CREATE, ALTER, DROP)
• Added support for DML operations (INSERT, UPDATE, DELETE)
• Automatic .env loading from project directory
• Added dotenv dependency

v1.0.0

• Initial release with SELECT query support
• Table listing and description
• Connection pooling

Development

# Install dependencies
npm install

# Build
npm run build

# Run
npm start

# Development with auto-reload
npm run dev

Requirements

• Node.js >= 18
• SQL Server with SQL authentication enabled

License

ISC