Skip to content
Back to search

mssql-mcp

MSSQL Server MCP implementation written in C#

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aaronontheweb--mssql-mcp/badge.svg)](/listings/aaronontheweb--mssql-mcp)

HTML

<a href="/listings/aaronontheweb--mssql-mcp"><img src="/api/listings/aaronontheweb--mssql-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 426 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # mssql-mcp
  2. A .NET-powered Model Context Protocol (MCP) server for Microsoft SQL Server.
  3. ## Abstract
  4. 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.
  5. 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.
  6. ## Features
  7. - **Schema Discovery**: AI agents can explore database structure without writing complex SQL
  8. - **Query Execution**: Full SQL support for SELECT, INSERT, UPDATE, DELETE, and DDL operations
  9. - **Connection Validation**: Automatic database connectivity validation on startup
  10. - **Error Handling**: Comprehensive error handling with clear, actionable error messages
  11. - **Table Formatting**: Query results formatted in readable tables for AI consumption
  12. - **Docker Support**: Easy deployment with built-in .NET Docker tooling
  13. ## Available Tools
  14. | Tool | Description |
  15. |------|-------------|
  16. | `execute_sql` | Execute any SQL query against the database |
  17. | `list_tables` | List all tables with schema, name, type, and row count |
  18. | `list_schemas` | List all available schemas/databases in the SQL Server instance |
  19. ## Configuration
  20. ### Required Environment Variables
  21. The MCP server requires a single environment variable:
  22. - **`MSSQL_CONNECTION_STRING`**: Complete SQL Server connection string
  23. #### Example Connection Strings
  24. **Windows Authentication:**
  25. ```
  26. MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDatabase;Trusted_Connection=true;"
  27. ```
  28. **SQL Server Authentication:**
  29. ```
  30. MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDatabase;User Id=myuser;Password=mypassword;"
  31. ```
  32. **Azure SQL Database:**
  33. ```
  34. MSSQL_CONNECTION_STRING="Server=myserver.database.windows.net;Database=mydatabase;User Id=myuser;Password=mypassword;Encrypt=true;"
  35. ```
  36. ## Running the MCP Server
  37. ### Option 1: Docker (Recommended)
  38. The easiest way to run the MCP server is using Docker with .NET's built-in container support.
  39. #### Build and Run with Docker
  40. Clone the repository
  41. ```bash
  42. # Clone the repository
  43. git clone https://github.com/Aaronontheweb/mssql-mcp.git
  44. cd mssql-mcp
  45. ```
  46. Build the Docker image
  47. ```bash
  48. dotnet publish --os linux --arch x64 /t:PublishContainer
  49. ```
  50. You can run the container directly if you wish, but it's **probably best** to let the MCP server spin up the client:
  51. ```bash
  52. # Run the container
  53. docker run -it --rm \
  54. -e MSSQL_CONNECTION_STRING="Server=host.docker.internal;Database=MyDB;Trusted_Connection=true;" \
  55. mssql-mcp:latest
  56. ```
  57. ## MCP Client Configuration
  58. ### Cursor IDE
  59. Add to your Cursor settings (`Cursor Settings > Features > Model Context Protocol`):
  60. ```json
  61. {
  62. "mcpServers": {
  63. "mssql": {
  64. "command": "docker",
  65. "args": [
  66. "run",
  67. "-i",
  68. "--rm",
  69. "-e",
  70. "MSSQL_CONNECTION_STRING",
  71. "mssql-mcp:latest"
  72. ],
  73. "env": {
  74. "MSSQL_CONNECTION_STRING": "Server=host.docker.internal,1533; Database=MyDb; User Id=myUser; Password=My(!)Password;TrustServerCertificate=true;"
  75. }
  76. }
  77. }
  78. }
  79. ```
  80. ### Claude Desktop
  81. Add to your Claude Desktop configuration file:
  82. * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
  83. * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
  84. ```json
  85. {
  86. "mcpServers": {
  87. "mssql": {
  88. "command": "docker",
  89. "args": [
  90. "run",
  91. "-i",
  92. "--rm",
  93. "-e",
  94. "MSSQL_CONNECTION_STRING",
  95. "mssql-mcp:latest"
  96. ],
  97. "env": {
  98. "MSSQL_CONNECTION_STRING": "Server=host.docker.internal,1533; Database=MyDb; User Id=myUser; Password=My(!)Password;TrustServerCertificate=true;"
  99. }
  100. }
  101. }
  102. }
  103. ```
  104. You might need to create that file and restart Claude Desktop for the changes to take effect.
  105. #### Understanding Your Claude Desktop MCP Server Configuration
  106. This JSON configuration is for **Claude Desktop's Model Context Protocol (MCP) servers**. It essentially teaches Claude how to connect to and use a custom
  107. "tool" that interacts with a **Microsoft SQL Server (MSSQL)** database.
  108. Let's break down each part:
  109. ##### `mcpServers`
  110. 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.
  111. ##### `"mssql"`
  112. This is the **unique name** you've chosen for this particular SQL Server integration. Claude will use this name to refer to this database connection.
  113. ##### `"command": "docker"`
  114. This line tells Claude Desktop to launch the MCP server using **Docker**. This means the actual server software runs inside an isolated container,
  115. and you'll need **Docker Desktop** installed and running on your Windows/mac/Linux machine for this to work. Alternatively, you can use remote Docker server
  116. using [custon context](https://docs.docker.com/engine/manage-resources/contexts/).
  117. ##### `"args": [...]`
  118. These are the **arguments** Claude Desktop passes to the `docker` command when starting the container:
  119. * `"run"`: This standard Docker command creates and starts a new container.
  120. * `"-i"`: Stands for "interactive," keeping the standard input open for communication between the MCP server and Claude Desktop.
  121. * `"--rm"`: This important argument tells Docker to **automatically remove the container** when it stops. This helps keep your Docker environment tidy.
  122. * `"-e", "MSSQL_CONNECTION_STRING"`: This passes an **environment variable** named `MSSQL_CONNECTION_STRING` into the Docker container.
  123. * `"mssql-mcp:latest"`: This specifies the **Docker image** to use. This image (`mssql-mcp` with the `latest` tag) contains the actual MCP server application
  124. designed to interact with SQL Server. You'll need to ensure this image is available (either built locally or pulled from a Docker registry).
  125. ##### `"env": {...}`
  126. This section defines the **environment variables** that will be set when Docker executes the command.
  127. * `"MSSQL_CONNECTION_STRING": "Server=host.docker.internal,1533; Database=MyDb; User Id=myUser; Password=My(!)Password;TrustServerCertificate=true;"`
  128. * This is the **SQL Server connection string** that the `mssql-mcp` Docker container will use to connect to your database.
  129. * `Server=host.docker.internal,1533`: `host.docker.internal` is a special Docker DNS name that lets the container reach your **host machine's IP address**.
  130. This is how the MCP server inside Docker can connect to your SQL Server instance, which is presumably running directly on your machine. `1533` is the
  131. port your SQL Server is listening on.
  132. * `Database=MyDb`: The name of the specific database you want to connect to.
  133. * `User Id=myUser; Password=My(!)Password;`: The credentials for a user (`myUser`) to log into your SQL Server.
  134. * `TrustServerCertificate=true;`: This tells the client to **skip validating the server's SSL/TLS certificate**. While convenient for development or when
  135. using self-signed certificates, be aware this reduces security by making you vulnerable to man-in-the-middle attacks in production environments.
  136. ---
  137. ##### In a Nutshell:
  138. This configuration enables Claude Desktop to run a SQL Server-specific MCP server inside a Docker container. This server then uses the provided connection
  139. string to establish a connection to your SQL Server database, allowing Claude to interact with your data through this custom tool.
  140. ### Local Binary Configuration
  141. If running the built binary directly instead of Docker:
  142. ```json
  143. {
  144. "mcpServers": {
  145. "mssql": {
  146. "command": "/path/to/mssql-mcp/src/MSSQL.MCP/bin/Release/net9.0/MSSQL.MCP",
  147. "env": {
  148. "MSSQL_CONNECTION_STRING": "Server=localhost;Database=MyDB;Trusted_Connection=true;"
  149. }
  150. }
  151. }
  152. }
  153. ```
  154. ## Docker Networking Issues
  155. ### Understanding the Problem
  156. When running the MCP server as a Docker container, you'll encounter networking challenges when trying to connect to SQL Server instances running on your host machine or in other containers. Docker containers are isolated from the host network by default, making `localhost` connections impossible.
  157. ### Solutions by Scenario
  158. #### Scenario 1: SQL Server Running on Host Machine
  159. **Problem**: Your SQL Server is installed directly on Windows/macOS/Linux, and you want the containerized MCP server to connect to it.
  160. **Solution**: Use `host.docker.internal` instead of `localhost` in your connection string.
  161. ```bash
  162. # ❌ This won't work - localhost refers to the container itself
  163. docker run -it --rm \
  164. -e MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDB;User Id=sa;Password=YourPassword123!;" \
  165. mssql-mcp:latest
  166. # ✅ This works - host.docker.internal refers to the host machine
  167. docker run -it --rm \
  168. -e MSSQL_CONNECTION_STRING="Server=host.docker.internal;Database=MyDB;User Id=sa;Password=YourPassword123!;" \
  169. mssql-mcp:latest
  170. ```
  171. **Updated MCP Client Configuration:**
  172. ```json
  173. {
  174. "mcpServers": {
  175. "mssql": {
  176. "command": "docker",
  177. "args": [
  178. "run", "-i", "--rm",
  179. "-e", "MSSQL_CONNECTION_STRING=Server=host.docker.internal;Database=MyDB;User Id=sa;Password=YourPassword123!;",
  180. "mssql-mcp:latest"
  181. ]
  182. }
  183. }
  184. }
  185. ```
  186. #### Scenario 2: SQL Server in Another Docker Container
  187. **Solution**: Use Docker Compose with a custom network and reference containers by service name.
  188. ```yaml
  189. version: '3.8'
  190. networks:
  191. sql-network:
  192. driver: bridge
  193. services:
  194. mssql-mcp:
  195. build: .
  196. environment:
  197. # Use the service name 'sqlserver' as the hostname
  198. - MSSQL_CONNECTION_STRING=Server=sqlserver;Database=MyDatabase;User Id=sa;Password=YourPassword123!;
  199. stdin_open: true
  200. tty: true
  201. networks:
  202. - sql-network
  203. depends_on:
  204. - sqlserver
  205. sqlserver:
  206. image: mcr.microsoft.com/mssql/server:2022-latest
  207. environment:
  208. - ACCEPT_EULA=Y
  209. - SA_PASSWORD=YourPassword123!
  210. networks:
  211. - sql-network
  212. ports:
  213. - "1433:1433" # Expose to host for external tools
  214. ```
  215. #### Scenario 3: Linux with Host Network Mode
  216. **Linux Only Solution**: Use Docker's host networking mode for direct host network access.
  217. ```bash
  218. # Linux only - shares the host's network stack
  219. docker run -it --rm --network host \
  220. -e MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDB;User Id=sa;Password=YourPassword123!;" \
  221. mssql-mcp:latest
  222. ```
  223. ### Platform-Specific Considerations
  224. | Platform | host.docker.internal | Host Network Mode | Recommended Solution |
  225. |----------|---------------------|-------------------|---------------------|
  226. | **Windows** | ✅ Works out of box | ❌ Not supported | Use `host.docker.internal` |
  227. | **macOS** | ✅ Works out of box | ❌ Not supported | Use `host.docker.internal` |
  228. | **Linux** | ⚠️ Requires `--add-host` | ✅ Supported | Use `--network host` or `host.docker.internal` |
  229. **Linux `host.docker.internal` setup:**
  230. ```bash
  231. docker run -it --rm \
  232. --add-host=host.docker.internal:host-gateway \
  233. -e MSSQL_CONNECTION_STRING="Server=host.docker.internal;Database=MyDB;User Id=sa;Password=YourPassword123!;" \
  234. mssql-mcp:latest
  235. ```
  236. ### Testing Network Connectivity
  237. To verify your container can reach the SQL Server:
  238. ```bash
  239. # Test from inside a running container
  240. docker exec -it <container_name> ping host.docker.internal
  241. # Test SQL Server port specifically
  242. docker run --rm -it mcr.microsoft.com/mssql-tools \
  243. /bin/bash -c "sqlcmd -S host.docker.internal -U sa -P 'YourPassword123!' -Q 'SELECT @@VERSION'"
  244. ```
  245. ### Common Networking Troubleshooting
  246. 1. **Connection Refused**:
  247. - Verify SQL Server is listening on all interfaces: `netstat -an | grep 1433`
  248. - Check Windows Firewall allows Docker subnet access
  249. 2. **DNS Resolution**:
  250. - Test: `docker run --rm busybox nslookup host.docker.internal`
  251. - Ensure Docker Desktop is running (for Windows/macOS)
  252. 3. **Container-to-Container**:
  253. - Verify both containers are on the same Docker network
  254. - Use container service names, not localhost
  255. 4. **Port Conflicts**:
  256. - Ensure port 1433 isn't already bound by another process
  257. - Check with: `netstat -tlnp | grep 1433`
  258. ## Usage Examples
  259. Once configured, AI agents can use natural language to interact with your database:
  260. **"Show me all the tables in the database"**
  261. → Uses `list_tables` tool
  262. **"Describe the structure of the Users table"**
  263. → Uses `execute_sql` with an INFORMATION_SCHEMA query
  264. **"Find all users created in the last 30 days"**
  265. → Uses `execute_sql` with appropriate SELECT query
  266. **"Create a new customer record"**
  267. → Uses `execute_sql` with INSERT statement
  268. ## Security Considerations
  269. ### ⚠️ Important Security Warnings
  270. - **Database Permissions**: Only grant the minimum required permissions to the database user
  271. - **Connection Security**: Use encrypted connections for production environments
  272. - **Access Control**: This MCP server provides full SQL execution capabilities - ensure proper access controls
  273. - **Audit Logging**: Consider enabling SQL Server audit logging for production use
  274. - **Network Security**: Restrict network access to the database server appropriately
  275. ### Recommended Database Permissions
  276. For read-only access:
  277. ```sql
  278. -- Create a dedicated user with minimal permissions
  279. CREATE LOGIN mcp_readonly WITH PASSWORD = 'SecurePassword123!';
  280. CREATE USER mcp_readonly FOR LOGIN mcp_readonly;
  281. -- Grant only necessary permissions
  282. GRANT SELECT ON SCHEMA::dbo TO mcp_readonly;
  283. GRANT VIEW DEFINITION ON SCHEMA::dbo TO mcp_readonly;
  284. ```
  285. For read-write access:
  286. ```sql
  287. -- Create a dedicated user
  288. CREATE LOGIN mcp_readwrite WITH PASSWORD = 'SecurePassword123!';
  289. CREATE USER mcp_readwrite FOR LOGIN mcp_readwrite;
  290. -- Grant necessary permissions
  291. GRANT SELECT, INSERT, UPDATE, DELETE ON SCHEMA::dbo TO mcp_readwrite;
  292. GRANT VIEW DEFINITION ON SCHEMA::dbo TO mcp_readwrite;
  293. ```
  294. ## Troubleshooting
  295. ### Connection Issues
  296. 1. **Verify connection string**: Test with SQL Server Management Studio or Azure Data Studio
  297. 2. **Check firewall**: Ensure SQL Server port (default 1433) is accessible
  298. 3. **Enable TCP/IP**: Ensure TCP/IP protocol is enabled in SQL Server Configuration Manager
  299. 4. **Authentication mode**: Verify SQL Server is configured for the appropriate authentication mode
  300. ### Container Issues
  301. 1. **Network connectivity**: Use `host.docker.internal` instead of `localhost` when connecting from container to host
  302. 2. **Environment variables**: Ensure the connection string is properly escaped in Docker commands
  303. 3. **Logs**: Check container logs with `docker logs <container_id>`
  304. ## License
  305. 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 agent `sa` access through this MCP server, we're not responsible.
  306. ## Contributing
  307. 1. Fork the repository
  308. 2. Create a feature branch
  309. 3. Make your changes
  310. 4. Add tests if applicable
  311. 5. Submit a pull request
  312. ## Architecture
  313. - **[Akka.NET](https://getakka.net/)**: Used for internal actor system coordination and database validation
  314. - **[MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk)**: Official Model Context Protocol implementation
  315. - **Microsoft.Data.SqlClient**: High-performance SQL Server connectivity

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.