MSSQL MCP Server

MSSQL MCP Server is a Model Context Protocol (MCP) server that enables secure and structured interaction with Microsoft SQL Server (MSSQL) databases. It allows AI assistants to:

• List available tables
• Read table contents
• Execute SQL queries with controlled access

Built on MCP SDK v2 (2026-07-28 spec) with support for both stdio and Streamable HTTP transports.

Features

• Secure MSSQL Database Access through environment variables
• SQL Injection Protection with identifier validation
• Read-Only & Write Tools with appropriate MCP annotations
• Windows Authentication support via Trusted Connection
• Dual Transport — stdio (default) and HTTP
• Docker Support with pre-configured ODBC drivers
• Comprehensive Logging for monitoring queries and operations

Installation

pip install mssql-mcp-server

Configuration

Set the following environment variables to configure database access:

# Required
MSSQL_DATABASE=your_database

# Authentication (choose one):
# Option 1: SQL Server Authentication
MSSQL_USER=your_username
MSSQL_PASSWORD=your_password

# Option 2: Windows / Kerberos Authentication
Trusted_Connection=yes

# Optional
MSSQL_HOST=localhost           # or use MSSQL_SERVER
MSSQL_DRIVER=SQL Server        # default driver
TrustServerCertificate=no      # default: no (set to yes for self-signed certs)
MCP_TRANSPORT=stdio            # or "streamable-http" for Streamable HTTP

Available Tools

Usage

With Claude Desktop

Add this configuration to `claude_desktop_config.json`:

{
  "mcpServers": {
    "mssql": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mssql_mcp_server",
        "run",
        "mssql_mcp_server"
      ],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_USER": "your_username",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_DATABASE": "your_database"
      }
    }
  }
}

With Cursor IDE

Add this to your `.cursor/mcp.json`:

{
  "mcpServers": {
    "mssql": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mssql_mcp_server",
        "run",
        "mssql_mcp_server"
      ],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_USER": "your_username",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_DATABASE": "your_database"
      }
    }
  }
}

With pip install (global)

{
  "mcpServers": {
    "mssql": {
      "command": "mssql_mcp_server",
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_USER": "your_username",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_DATABASE": "your_database"
      }
    }
  }
}

With Docker

docker build -t mssql-mcp-server .
docker run -e MSSQL_HOST=host.docker.internal \
           -e MSSQL_USER=your_username \
           -e MSSQL_PASSWORD=your_password \
           -e MSSQL_DATABASE=your_database \
           mssql-mcp-server

Running as a Standalone Server

# Install dependencies
pip install -r requirements.txt

# Run the server (stdio)
python -m mssql_mcp_server

# Run with HTTP transport
MCP_TRANSPORT=streamable-http python -m mssql_mcp_server

Development & Testing

# Clone the repository
git clone https://github.com/JexinSam/mssql_mcp_server.git
cd mssql_mcp_server

# Set up a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements-dev.txt
pip install -e .

# Run tests
pytest -v

# Test with MCP Inspector
uv run mcp dev src/mssql_mcp_server/server.py

Troubleshooting

"Program Not Found" Error

This usually means the `mssql_mcp_server` command is not in your PATH. Solutions:

1. Use `uv` (recommended): Configure your MCP client to use `uv --directory path/to/mssql_mcp_server run mssql_mcp_server`

2. Use full path: Find the install location with `pip show mssql-mcp-server` and use the scripts directory

3. Use `python -m`: Run as `python -m mssql_mcp_server`

MSSQL Driver Issues

The default driver is `SQL Server` (built into Windows). For Linux/macOS or newer features:

1. Install Microsoft ODBC Driver 18

2. Set `MSSQL_DRIVER="ODBC Driver 18 for SQL Server"`

Connection Timeouts

If using `MSSQL_SERVER` from other projects, this server supports both `MSSQL_HOST` and `MSSQL_SERVER` env vars (with `MSSQL_HOST` taking priority).

Security Considerations

• Use a dedicated MSSQL user with minimal privileges.
• Never use root credentials or full administrative accounts.
• Restrict database access to only necessary operations (e.g. use `GRANT SELECT` only if the model should not modify data). The `readOnlyHint` and `destructiveHint` annotations are for client UX; security is enforced entirely by your database credentials.
• Enable logging and auditing for security monitoring.
• Regularly review permissions to ensure least privilege access.

Security Best Practices

For a secure setup:

1. Create a dedicated MSSQL user with restricted permissions.

2. Avoid hardcoding credentials—use environment variables instead.

3. Restrict access to necessary tables and operations only.

4. Enable SQL Server logging and monitoring for auditing.

5. Review database access regularly to prevent unauthorized access.

For detailed instructions, refer to the **MSSQL Security Configuration Guide**.

⚠️ IMPORTANT: Always follow the Principle of Least Privilege when configuring database access.

License

This project is licensed under the MIT License. See the `LICENSE` file for details.

Contributing

We welcome contributions! To contribute:

1. Fork the repository.

2. Create a feature branch: `git checkout -b feature/amazing-feature`

3. Commit your changes: `git commit -m 'Add amazing feature'`

4. Push to the branch: `git push origin feature/amazing-feature`

5. Open a Pull Request.

Need Help?

For any questions or issues, feel free to open a GitHub **Issue** or reach out to the maintainers.