Microsoft SQL Server MCP

A .NET-powered MCP server for interacting with Microsoft SQL Server databases.

A.NET-powered Model Context Protocol (MCP) server for Microsoft SQL Server.

Why does this exist? Because the other MCP solutions in market for this are generally janky pieces of shit that don't work - certainly not on Windows.

This MCP server provides AI agents with robust, reliable access to Microsoft SQL Server databases through a clean, well-architected.NET application using Akka.NET for internal coordination and the official MCP C# SDK for protocol compliance.

- Schema Discovery: AI agents can explore database structure without writing complex SQL
- Query Execution: Full SQL support for SELECT, INSERT, UPDATE, DELETE, and DDL operations
- Connection Validation: Automatic database connectivity validation on startup
- Error Handling: Comprehensive error handling with clear, actionable error messages
- Table Formatting: Query results formatted in readable tables for AI consumption
- Docker Support: Easy deployment with built-in.NET Docker tooling

The MCP server requires a single environment variable:

- MSSQL_CONNECTION_STRING: Complete SQL Server connection string

MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDatabase;Trusted_Connection=true;"

MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDatabase;User Id=myuser;Password=mypassword;"

MSSQL_CONNECTION_STRING="Server=myserver.database.windows.net;Database=mydatabase;User Id=myuser;Password=mypassword;Encrypt=true;"

The easiest way to run the MCP server is using Docker with.NET's built-in container support.

# Clone the repository git clone https://github.com/Aaronontheweb/mssql-mcp.git cd mssql-mcp

dotnet publish --os linux --arch x64 /t:PublishContainer

You can run the container directly if you wish, but it'sprobably bestto let the MCP server spin up the client:

# Run the container docker run -it --rm \ -e MSSQL_CONNECTION_STRING="Server=host.docker.internal;Database=MyDB;Trusted_Connection=true;" \ mssql-mcp:latest

Add to your Cursor settings (Cursor Settings > Features > Model Context Protocol):

{ "mcpServers": { "mssql": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MSSQL_CONNECTION_STRING", "mssql-mcp:latest" ], "env": { "MSSQL_CONNECTION_STRING": "Server=host.docker.internal,1533; Database=MyDb; User Id=myUser; Password=My(!)Password;TrustServerCertificate=true;" } } } }

Add to your Claude Desktop configuration file:

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

{ "mcpServers": { "mssql": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MSSQL_CONNECTION_STRING", "mssql-mcp:latest" ], "env": { "MSSQL_CONNECTION_STRING": "Server=host.docker.internal,1533; Database=MyDb; User Id=myUser; Password=My(!)Password;TrustServerCertificate=true;" } } } }

You might need to create that file and restart Claude Desktop for the changes to take effect.

Understanding Your Claude Desktop MCP Server Configuration

This JSON configuration is forClaude Desktop's Model Context Protocol (MCP) servers. It essentially teaches Claude how to connect to and use a custom "tool" that interacts with aMicrosoft SQL Server (MSSQL)database.

This is the top-level section where you define all your custom MCP servers. You can set up multiple servers here, each with its own unique name.

This is theunique nameyou've chosen for this particular SQL Server integration. Claude will use this name to refer to this database connection.

This line tells Claude Desktop to launch the MCP server usingDocker. This means the actual server software runs inside an isolated container, and you'll needDocker Desktopinstalled and running on your Windows/mac/Linux machine for this to work. Alternatively, you can use remote Docker server usingcuston context.

{ "mcpServers": { "mssql": { "command": "/path/to/mssql-mcp/src/MSSQL.MCP/bin/Release/net9.0/MSSQL.MCP", "env": { "MSSQL_CONNECTION_STRING": "Server=localhost;Database=MyDB;Trusted_Connection=true;" } } } }

# ❌ This won't work - localhost refers to the container itself docker run -it --rm \ -e MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDB;User Id=sa;Password=YourPassword123!;" \ mssql-mcp:latest # ✅ This works - host.docker.internal refers to the host machine docker run -it --rm \ -e MSSQL_CONNECTION_STRING="Server=host.docker.internal;Database=MyDB;User Id=sa;Password=YourPassword123!;" \ mssql-mcp:latest

{ "mcpServers": { "mssql": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MSSQL_CONNECTION_STRING=Server=host.docker.internal;Database=MyDB;User Id=sa;Password=YourPassword123!;", "mssql-mcp:latest" ] } } }

Scenario 2: SQL Server in Another Docker Container

Solution: Use Docker Compose with a custom network and reference containers by service name.

version: '3.8' networks: sql-network: driver: bridge services: mssql-mcp: build: . environment: # Use the service name 'sqlserver' as the hostname - MSSQL_CONNECTION_STRING=Server=sqlserver;Database=MyDatabase;User Id=sa;Password=YourPassword123!; stdin_open: true tty: true networks: - sql-network depends_on: - sqlserver sqlserver: image: mcr.microsoft.com/mssql/server:2022-latest environment: - ACCEPT_EULA=Y - SA_PASSWORD=YourPassword123! networks: - sql-network ports: - "1433:1433" # Expose to host for external tools

Scenario 3: Linux with Host Network Mode

Linux Only Solution: Use Docker's host networking mode for direct host network access.

# Linux only - shares the host's network stack docker run -it --rm --network host \ -e MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDB;User Id=sa;Password=YourPassword123!;" \ mssql-mcp:latest

docker run -it --rm \ --add-host=host.docker.internal:host-gateway \ -e MSSQL_CONNECTION_STRING="Server=host.docker.internal;Database=MyDB;User Id=sa;Password=YourPassword123!;" \ mssql-mcp:latest

To verify your container can reach the SQL Server:

# Test from inside a running container docker exec -it <container_name> ping host.docker.internal # Test SQL Server port specifically docker run --rm -it mcr.microsoft.com/mssql-tools \ /bin/bash -c "sqlcmd -S host.docker.internal -U sa -P 'YourPassword123!' -Q 'SELECT @@VERSION'"

- Connection Refused:

- Verify SQL Server is listening on all interfaces:netstat -an | grep 1433

- Check Windows Firewall allows Docker subnet access

- Test:docker run --rm busybox nslookup host.docker.internal

- Ensure Docker Desktop is running (for Windows/macOS)

- Verify both containers are on the same Docker network

- Use container service names, not localhost

- Ensure port 1433 isn't already bound by another process

- Check with:netstat -tlnp | grep 1433

Once configured, AI agents can use natural language to interact with your database:

"Show me all the tables in the database"→ Useslist_tablestool

"Describe the structure of the Users table"→ Usesexecute_sqlwith an INFORMATION_SCHEMA query

"Find all users created in the last 30 days"→ Usesexecute_sqlwith appropriate SELECT query

"Create a new customer record"→ Usesexecute_sqlwith INSERT statement

- Database Permissions: Only grant the minimum required permissions to the database user
- Connection Security: Use encrypted connections for production environments
- Access Control: This MCP server provides full SQL execution capabilities - ensure proper access controls
- Audit Logging: Consider enabling SQL Server audit logging for production use
- Network Security: Restrict network access to the database server appropriately

-- Create a dedicated user with minimal permissions CREATE LOGIN mcp_readonly WITH PASSWORD = 'SecurePassword123!'; CREATE USER mcp_readonly FOR LOGIN mcp_readonly; -- Grant only necessary permissions GRANT SELECT ON SCHEMA::dbo TO mcp_readonly; GRANT VIEW DEFINITION ON SCHEMA::dbo TO mcp_readonly;

-- Create a dedicated user CREATE LOGIN mcp_readwrite WITH PASSWORD = 'SecurePassword123!'; CREATE USER mcp_readwrite FOR LOGIN mcp_readwrite; -- Grant necessary permissions GRANT SELECT, INSERT, UPDATE, DELETE ON SCHEMA::dbo TO mcp_readwrite; GRANT VIEW DEFINITION ON SCHEMA::dbo TO mcp_readwrite;

- Verify connection string: Test with SQL Server Management Studio or Azure Data Studio
- Check firewall: Ensure SQL Server port (default 1433) is accessible
- Enable TCP/IP: Ensure TCP/IP protocol is enabled in SQL Server Configuration Manager
- Authentication mode: Verify SQL Server is configured for the appropriate authentication mode
- Network connectivity: Usehost.docker.internalinstead oflocalhostwhen connecting from container to host
- Environment variables: Ensure the connection string is properly escaped in Docker commands
- Logs: Check container logs withdocker logs <container_id>

This software is licensed under Apache 2.0 and is available "as is" - this means that if you turbo-nuke your database because you gave an AI agentsaaccess through this MCP server, we're not responsible.

Official MCP server for dbt (data build tool) providing integration with dbt Core/Cloud CLI, project metadata discovery, model information, and semantic layer querying capabilities.

Open source MCP server specializing in easy, fast, and secure tools for Databases.

Query and analyze data with MotherDuck and local DuckDB

Query Streams securely connects MCP clients to live databases through the Query Streams Cloud Network, with no VPNs, inbound ports, or complex setup.

Interact with the SingleStore database platform

Official Supabase MCP server for managing Supabase projects, databases, auth, storage, edge functions, and SQL workflows from AI agents.

A collection of tools for managing the platform, addressing data quality and reading and writing to Teradata Database.

Multi-database agent access (PostgreSQL, SQLite, MySQL, Oracle, SQL Server) with batch queries, pre-configured connections, and SQLGlot-enforced read-only safety