MSSQL MCP Server

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

Tool	Description	Annotations
list_tables	List all tables in the database	Read-only, Idempotent
query_sql	Execute read-only SELECT queries	Read-only, Idempotent
execute_sql	Execute any SQL statement (SELECT, INSERT, UPDATE, DELETE, DDL)	Destructive

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.