MSSQL Database MCP Server

An enterprise-grade Model Context Protocol (MCP) server for Microsoft SQL Server. This server enables AI assistants (like Claude, Cursor, Windsurf) to securely interact with MSSQL databases to query data, inspect schemas, and retrieve metadata.

Features

• Read-Only by Default: Strict safety controls to prevent accidental writes.
• Schema Introspection: Tools to list databases, tables, and describe table schemas.
• Secure Authentication: Supports SQL Server authentication with encryption.
• Docker Ready: Easy deployment using Docker or Docker Compose.
• Comprehensive Logging: Structured JSON logging for auditing.

Quick Start

1. Build the Docker Image

docker build -t mssql-mcp-server:latest .

2. Configure Environment

Create a .env file based on .env.example:

cp .env.example .env

Edit .env with your MSSQL connection details:

MSSQL_HOST=host.docker.internal
MSSQL_PORT=1433
MSSQL_DATABASE=master
MSSQL_USER=sa
MSSQL_PASSWORD=YourStrong@Passw0rd
MSSQL_ENCRYPT=true
MSSQL_TRUST_SERVER_CERTIFICATE=true

3. Run with Docker Compose

docker-compose up -d

Tools Available

The server exposes the following MCP tools:

Core Tools (Always Available)

• mssql_query: Execute SELECT queries (with safety checks)
• mssql_list_databases: List all accessible databases
• mssql_list_tables: List tables in a specific database/schema
• mssql_describe_table: Get detailed schema information (columns, PKs) for a table
• mssql_pool_stats: Get connection pool statistics for monitoring

Advanced Tools (Require Write Operations Enabled)

⚠️ These tools require MSSQL_ALLOW_WRITE_OPERATIONS=true

• mssql_execute_procedure: Execute stored procedures with parameters
• mssql_execute_write: Execute INSERT, UPDATE, DELETE statements with transaction safety

Performance Features

Connection Pooling

The server implements intelligent connection pooling for optimal performance:

• Reusable Connections: Connections are pooled and reused across queries
• Thread-Safe: Safe for concurrent requests
• Auto-Validation: Connections are validated before use
• Configurable Limits: Control min/max pool size via environment variables
• Connection Lifetime: Automatic rotation of long-lived connections
• Monitoring: Track pool usage with mssql_pool_stats tool

Configuration:

MIN_POOL_SIZE=2          # Minimum connections to maintain
MAX_POOL_SIZE=10         # Maximum concurrent connections
IDLE_TIMEOUT=300         # Seconds before idle connection closes
CONNECTION_LIFETIME=1800 # Max lifetime of a connection (30 min)

Monitor Pool Health:

{
  "total_connections": 5,
  "available_connections": 3,
  "max_connections": 10,
  "min_connections": 2
}

IDE Integration

For detailed integration instructions for Claude Desktop, Cursor, and Windsurf, see IDE-INTEGRATION.md.

Example Configuration (Generic)

Add this to your IDE's MCP configuration file:

{
  "mcpServers": {
    "mssql": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network", "host",
        "-e", "MSSQL_HOST=localhost",
        "-e", "MSSQL_USER=sa",
        "-e", "MSSQL_PASSWORD=password",
        "mssql-mcp-server:latest"
      ]
    }
  }
}

Development & Testing

The project includes an automated test suite that spins up a test MSSQL container.

Run Tests

# Make scripts executable
chmod +x test-runner.sh

# Run full integration test suite
./test-runner.sh

Project Structure

• src/: Source code
  • server.py: Main MCP server entry point
  • tools/: MCP tool implementations
  • database/: Database connection and validation logic
• tests/: Integration tests
• docker/: Docker configuration

Security Notes

• Write Operations: Disabled by default. To enable, set MSSQL_ALLOW_WRITE_OPERATIONS=true.
• Credentials: Never commit .env files. Use Docker secrets in production.
• Network: Use TLS (MSSQL_ENCRYPT=true) for non-local connections.

Support This Project

If you find this MSSQL MCP Server useful for your projects, please consider supporting its development!

☕ Become a Patron

This project is maintained by independent developers. Your support helps us:

• 🚀 Add new features and improvements
• 🐛 Fix bugs and improve stability
• 📚 Create better documentation and tutorials
• 🔒 Enhance security features
• 🎯 Provide faster support and updates

Support us on Patreon

Supporter Benefits

Patrons get access to:

• 🎯 Priority Support - Get help faster when you need it
• 📝 Early Access - Try new features before public release
• 💬 Direct Communication - Influence the project roadmap
• 🎓 Exclusive Tutorials - Advanced usage guides and examples
• 🏆 Recognition - Your name in our SUPPORTERS.md file

Other Ways to Support

• ⭐ Star this repository on GitHub
• 🐛 Report bugs and request features via GitHub Issues
• 📖 Improve documentation by submitting pull requests
• 💬 Spread the word - Share with colleagues and on social media

---

License

This project is licensed under the MIT License - see the LICENSE file for details.