MSSQL MCP Server

A Model Context Protocol (MCP) server implementation for Microsoft SQL Server. This server enables AI assistants like Claude to interact with MSSQL databases through a standardized interface.

Features

🚀 Execute SQL Queries: Run any SQL query with proper error handling and result formatting
📊 Browse Database Schema: List tables, view table structures, and sample data
🔧 Multi-line Query Support: Correctly handles queries with newlines, comments, and GO statements
🔐 Flexible Authentication: Supports both Windows (trusted) and SQL authentication
⚙️ Environment Configuration: Easy setup via environment variables
🛡️ Security: Connection string encryption, certificate trust options, and secure credential handling

Installation

From PyPI

pip install mssql-mcp-server-enhanced

From Source

git clone https://github.com/combiz/mssql-mcp-server.git
cd mssql-mcp-server
pip install -e .

Prerequisites

Python 3.8+

ODBC Driver for SQL Server - Install one of:

ODBC Driver 17 for SQL Server (recommended)
ODBC Driver 18 for SQL Server

Installation commands:

# Ubuntu/Debian
curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
sudo apt-get install -y msodbcsql17

# macOS
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
brew install msodbcsql17

# Windows - Download installer from Microsoft

Configuration

Configure the server using environment variables:

Required Variables

MSSQL_DATABASE - The database name to connect to

Connection Variables

MSSQL_HOST or MSSQL_SERVER - Server hostname (default: localhost)
MSSQL_PORT - Server port (default: 1433)

Authentication Variables

For SQL Authentication:

MSSQL_USER - Username
MSSQL_PASSWORD - Password
MSSQL_TRUSTED_CONNECTION - Set to no (default: no)

For Windows Authentication:

MSSQL_TRUSTED_CONNECTION - Set to yes
No username/password needed

Optional Variables

MSSQL_DRIVER - ODBC driver name (default: ODBC Driver 17 for SQL Server)
MSSQL_TRUST_SERVER_CERTIFICATE - Trust server certificate (default: yes)
MSSQL_ENCRYPT - Encrypt connection (default: yes)
MSSQL_CONNECTION_TIMEOUT - Connection timeout in seconds (default: 30)
MSSQL_MULTI_SUBNET_FAILOVER - Enable multi-subnet failover (default: no)

Usage

As a Standalone Server

# Set environment variables
export MSSQL_SERVER=your-server.database.windows.net
export MSSQL_DATABASE=your-database
export MSSQL_USER=your-username
export MSSQL_PASSWORD=your-password

# Run the server
python -m mssql_mcp_server.server

With MCP-Compatible Clients

Add to your MCP configuration file:

Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code: See Claude Code documentation for configuration location

Cursor: Add to your Cursor MCP settings

{
  "mcpServers": {
    "mssql": {
      "command": "python",
      "args": ["-m", "mssql_mcp_server.server"],
      "env": {
        "MSSQL_SERVER": "your-server.database.windows.net",
        "MSSQL_DATABASE": "your-database",
        "MSSQL_USER": "your-username",
        "MSSQL_PASSWORD": "your-password"
      }
    }
  }
}

Example Configurations

Azure SQL Database

export MSSQL_SERVER=myserver.database.windows.net
export MSSQL_DATABASE=mydatabase
export MSSQL_USER=myuser@myserver
export MSSQL_PASSWORD=mypassword
export MSSQL_ENCRYPT=yes
export MSSQL_TRUST_SERVER_CERTIFICATE=no

Local SQL Server with Windows Authentication

export MSSQL_SERVER=localhost
export MSSQL_DATABASE=mydatabase
export MSSQL_TRUSTED_CONNECTION=yes

SQL Server on Non-Standard Port

export MSSQL_SERVER=myserver.company.com
export MSSQL_PORT=1434
export MSSQL_DATABASE=mydatabase
export MSSQL_USER=sa
export MSSQL_PASSWORD=mypassword

MCP Configuration with Virtual Environment

For use with Claude Desktop, Claude Code, Cursor, or any MCP-compatible client. If you're using a Python virtual environment, specify the full path to the Python executable:

{
  "mcpServers": {
    "mssql": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "mssql_mcp_server.server"],
      "env": {
        "MSSQL_SERVER": "your-server-name",
        "MSSQL_DATABASE": "your-database",
        "MSSQL_DRIVER": "ODBC Driver 17 for SQL Server",
        "MSSQL_TRUST_SERVER_CERTIFICATE": "yes",
        "MSSQL_TRUSTED_CONNECTION": "yes",
        "MSSQL_ENCRYPT": "yes",
        "MSSQL_CONNECTION_TIMEOUT": "60",
        "MSSQL_PORT": "1433"
      }
    }
  }
}

Available Tools

execute_sql

Execute any SQL query on the connected database.

Parameters:

query (string, required): The SQL query to execute

Examples:

-- Simple SELECT
SELECT * FROM Users WHERE active = 1

-- Multi-line query with JOIN
SELECT 
    u.username,
    u.email,
    COUNT(o.id) as order_count
FROM Users u
LEFT JOIN Orders o ON u.id = o.user_id
GROUP BY u.username, u.email
HAVING COUNT(o.id) > 5

-- Create table
CREATE TABLE Products (
    id INT PRIMARY KEY IDENTITY(1,1),
    name NVARCHAR(100) NOT NULL,
    price DECIMAL(10,2),
    created_at DATETIME DEFAULT GETDATE()
)

-- Insert data
INSERT INTO Products (name, price)
VALUES ('Widget', 19.99), ('Gadget', 29.99)

Available Resources

The server exposes database tables as resources:

Schema Resource: mssql://database/schema.table/schema
- Shows table structure, column types, constraints
Data Resource: mssql://database/schema.table/data
- Shows sample data from the table (limited to 100 rows)

Query Preprocessing

The server automatically handles:

✅ Multi-line queries with proper newline handling
✅ SQL comments (both -- and /* */ styles)
✅ GO batch separators (executes first batch only with warning)
✅ String literals with embedded newlines
✅ Excessive whitespace cleanup

Error Handling

The server provides detailed error messages for:

Connection failures
Authentication errors
SQL syntax errors
Query execution errors
Invalid configurations

Security Considerations

Credentials: Use environment variables or secure credential stores. Never hardcode credentials.
Permissions: Use database users with minimal required permissions.
Connection Encryption: Enable MSSQL_ENCRYPT for production environments.
Certificate Validation: Set MSSQL_TRUST_SERVER_CERTIFICATE=no for production.
Query Validation: The server executes queries as-is. Ensure proper access controls at the database level.

Development

Running Tests

pip install -e ".[dev]"
pytest

Code Formatting

black mssql_mcp_server
flake8 mssql_mcp_server
mypy mssql_mcp_server

Troubleshooting

Connection Issues

"ODBC Driver X for SQL Server not found"
- Install the ODBC driver (see Prerequisites)
- Update MSSQL_DRIVER to match your installed driver
"Login failed for user"
- Verify credentials
- Check if SQL authentication is enabled on the server
- For Azure SQL, ensure username includes server name: user@server
"Cannot open server requested by the login"
- Verify server name/address
- Check firewall rules
- Ensure SQL Server is accepting TCP/IP connections

Query Issues

"Incorrect syntax near 'GO'"
- The server handles GO statements by executing only the first batch
- Split multi-batch scripts into separate queries
Hanging queries
- Check for unclosed transactions
- Verify query doesn't have syntax errors related to newlines
- Monitor query execution time with MSSQL_CONNECTION_TIMEOUT

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request

License

MIT License - see LICENSE file for details

Acknowledgments

Built on the Model Context Protocol
Uses pyodbc for database connectivity