{"id":29117741,"url":"https://github.com/aaronontheweb/mssql-mcp","last_synced_at":"2025-06-29T12:05:07.519Z","repository":{"id":298619630,"uuid":"1000557423","full_name":"Aaronontheweb/mssql-mcp","owner":"Aaronontheweb","description":"MSSQL Server MCP implementation written in C#","archived":false,"fork":false,"pushed_at":"2025-06-27T19:41:57.000Z","size":61,"stargazers_count":92,"open_issues_count":1,"forks_count":8,"subscribers_count":0,"default_branch":"dev","last_synced_at":"2025-06-27T20:35:05.130Z","etag":null,"topics":["csharp","dotnet","mcp","mcp-server","mssql","sqlserver"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Aaronontheweb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-12T01:21:56.000Z","updated_at":"2025-06-27T19:41:59.000Z","dependencies_parsed_at":"2025-06-12T02:49:10.517Z","dependency_job_id":"ba30abb4-2d31-4f87-b27e-387d3827278d","html_url":"https://github.com/Aaronontheweb/mssql-mcp","commit_stats":null,"previous_names":["aaronontheweb/mssql-mcp"],"tags_count":0,"template":false,"template_full_name":"akkadotnet/build-system-template","purl":"pkg:github/Aaronontheweb/mssql-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aaronontheweb%2Fmssql-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aaronontheweb%2Fmssql-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aaronontheweb%2Fmssql-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aaronontheweb%2Fmssql-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Aaronontheweb","download_url":"https://codeload.github.com/Aaronontheweb/mssql-mcp/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aaronontheweb%2Fmssql-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262589877,"owners_count":23333254,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csharp","dotnet","mcp","mcp-server","mssql","sqlserver"],"created_at":"2025-06-29T12:05:02.587Z","updated_at":"2025-06-29T12:05:07.506Z","avatar_url":"https://github.com/Aaronontheweb.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mssql-mcp\n\nA .NET-powered Model Context Protocol (MCP) server for Microsoft SQL Server.\n\n## Abstract\n\nWhy 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.\n\nThis 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.\n\n## Features\n\n- **Schema Discovery**: AI agents can explore database structure without writing complex SQL\n- **Query Execution**: Full SQL support for SELECT, INSERT, UPDATE, DELETE, and DDL operations\n- **Connection Validation**: Automatic database connectivity validation on startup\n- **Error Handling**: Comprehensive error handling with clear, actionable error messages\n- **Table Formatting**: Query results formatted in readable tables for AI consumption\n- **Docker Support**: Easy deployment with built-in .NET Docker tooling\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `execute_sql` | Execute any SQL query against the database |\n| `list_tables` | List all tables with schema, name, type, and row count |\n| `list_schemas` | List all available schemas/databases in the SQL Server instance |\n\n## Configuration\n\n### Required Environment Variables\n\nThe MCP server requires a single environment variable:\n\n- **`MSSQL_CONNECTION_STRING`**: Complete SQL Server connection string\n\n#### Example Connection Strings\n\n**Windows Authentication:**\n```\nMSSQL_CONNECTION_STRING=\"Server=localhost;Database=MyDatabase;Trusted_Connection=true;\"\n```\n\n**SQL Server Authentication:**\n```\nMSSQL_CONNECTION_STRING=\"Server=localhost;Database=MyDatabase;User Id=myuser;Password=mypassword;\"\n```\n\n**Azure SQL Database:**\n```\nMSSQL_CONNECTION_STRING=\"Server=myserver.database.windows.net;Database=mydatabase;User Id=myuser;Password=mypassword;Encrypt=true;\"\n```\n\n## Running the MCP Server\n\n### Option 1: Docker (Recommended)\n\nThe easiest way to run the MCP server is using Docker with .NET's built-in container support.\n\n#### Build and Run with Docker\n\nClone the repository\n\n```bash\n# Clone the repository\ngit clone https://github.com/Aaronontheweb/mssql-mcp.git\ncd mssql-mcp\n```\n\nBuild the Docker image\n\n```bash\ndotnet publish --os linux --arch x64 /t:PublishContainer\n```\n\nYou can run the container directly if you wish, but it's **probably best** to let the MCP server spin up the client:\n\n```bash\n# Run the container\ndocker run -it --rm \\\n  -e MSSQL_CONNECTION_STRING=\"Server=host.docker.internal;Database=MyDB;Trusted_Connection=true;\" \\\n  mssql-mcp:latest\n```\n\n## MCP Client Configuration\n\n### Cursor IDE\n\nAdd to your Cursor settings (`Cursor Settings \u003e Features \u003e Model Context Protocol`):\n\n```json\n{\n  \"mcpServers\": {\n    \"mssql\": {\n      \"command\": \"docker\",\n      \"args\": [\n          \"run\",\n          \"-i\",\n          \"--rm\",\n          \"-e\",\n          \"MSSQL_CONNECTION_STRING\",\n          \"mssql-mcp:latest\"\n      ],\n      \"env\": {\n          \"MSSQL_CONNECTION_STRING\": \"Server=host.docker.internal,1533; Database=MyDb; User Id=myUser; Password=My(!)Password;TrustServerCertificate=true;\"\n      }\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd to your Claude Desktop configuration file:\n\n* **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"mssql\": {\n      \"command\": \"docker\",\n      \"args\": [\n          \"run\",\n          \"-i\",\n          \"--rm\",\n          \"-e\",\n          \"MSSQL_CONNECTION_STRING\",\n          \"mssql-mcp:latest\"\n      ],\n      \"env\": {\n          \"MSSQL_CONNECTION_STRING\": \"Server=host.docker.internal,1533; Database=MyDb; User Id=myUser; Password=My(!)Password;TrustServerCertificate=true;\"\n      }\n    }\n  }\n}\n```\n\nYou might need to create that file and restart Claude Desktop for the changes to take effect.\n\n#### Understanding Your Claude Desktop MCP Server Configuration\n\nThis JSON configuration is for **Claude Desktop's Model Context Protocol (MCP) servers**. It essentially teaches Claude how to connect to and use a custom \n\"tool\" that interacts with a **Microsoft SQL Server (MSSQL)** database.\n\nLet's break down each part:\n\n##### `mcpServers`\n\nThis 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.\n\n##### `\"mssql\"`\n\nThis is the **unique name** you've chosen for this particular SQL Server integration. Claude will use this name to refer to this database connection.\n\n##### `\"command\": \"docker\"`\n\nThis line tells Claude Desktop to launch the MCP server using **Docker**. This means the actual server software runs inside an isolated container, \nand 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\nusing [custon context](https://docs.docker.com/engine/manage-resources/contexts/).\n\n##### `\"args\": [...]`\n\nThese are the **arguments** Claude Desktop passes to the `docker` command when starting the container:\n\n* `\"run\"`: This standard Docker command creates and starts a new container.\n* `\"-i\"`: Stands for \"interactive,\" keeping the standard input open for communication between the MCP server and Claude Desktop.\n* `\"--rm\"`: This important argument tells Docker to **automatically remove the container** when it stops. This helps keep your Docker environment tidy.\n* `\"-e\", \"MSSQL_CONNECTION_STRING\"`: This passes an **environment variable** named `MSSQL_CONNECTION_STRING` into the Docker container.\n* `\"mssql-mcp:latest\"`: This specifies the **Docker image** to use. This image (`mssql-mcp` with the `latest` tag) contains the actual MCP server application \n   designed to interact with SQL Server. You'll need to ensure this image is available (either built locally or pulled from a Docker registry).\n\n##### `\"env\": {...}`\n\nThis section defines the **environment variables** that will be set when Docker executes the command.\n\n* `\"MSSQL_CONNECTION_STRING\": \"Server=host.docker.internal,1533; Database=MyDb; User Id=myUser; Password=My(!)Password;TrustServerCertificate=true;\"`\n    * This is the **SQL Server connection string** that the `mssql-mcp` Docker container will use to connect to your database.\n    * `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**. \n       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 \n       port your SQL Server is listening on.\n    * `Database=MyDb`: The name of the specific database you want to connect to.\n    * `User Id=myUser; Password=My(!)Password;`: The credentials for a user (`myUser`) to log into your SQL Server.\n    * `TrustServerCertificate=true;`: This tells the client to **skip validating the server's SSL/TLS certificate**. While convenient for development or when \n      using self-signed certificates, be aware this reduces security by making you vulnerable to man-in-the-middle attacks in production environments.\n\n---\n##### In a Nutshell:\n\nThis configuration enables Claude Desktop to run a SQL Server-specific MCP server inside a Docker container. This server then uses the provided connection\nstring to establish a connection to your SQL Server database, allowing Claude to interact with your data through this custom tool.\n\n### Local Binary Configuration\n\nIf running the built binary directly instead of Docker:\n\n```json\n{\n  \"mcpServers\": {\n    \"mssql\": {\n      \"command\": \"/path/to/mssql-mcp/src/MSSQL.MCP/bin/Release/net9.0/MSSQL.MCP\",\n      \"env\": {\n        \"MSSQL_CONNECTION_STRING\": \"Server=localhost;Database=MyDB;Trusted_Connection=true;\"\n      }\n    }\n  }\n}\n```\n\n## Docker Networking Issues\n\n### Understanding the Problem\n\nWhen 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.\n\n### Solutions by Scenario\n\n#### Scenario 1: SQL Server Running on Host Machine\n\n**Problem**: Your SQL Server is installed directly on Windows/macOS/Linux, and you want the containerized MCP server to connect to it.\n\n**Solution**: Use `host.docker.internal` instead of `localhost` in your connection string.\n\n```bash\n# ❌ This won't work - localhost refers to the container itself\ndocker run -it --rm \\\n  -e MSSQL_CONNECTION_STRING=\"Server=localhost;Database=MyDB;User Id=sa;Password=YourPassword123!;\" \\\n  mssql-mcp:latest\n\n# ✅ This works - host.docker.internal refers to the host machine\ndocker run -it --rm \\\n  -e MSSQL_CONNECTION_STRING=\"Server=host.docker.internal;Database=MyDB;User Id=sa;Password=YourPassword123!;\" \\\n  mssql-mcp:latest\n```\n\n**Updated MCP Client Configuration:**\n```json\n{\n  \"mcpServers\": {\n    \"mssql\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\",\n        \"-e\", \"MSSQL_CONNECTION_STRING=Server=host.docker.internal;Database=MyDB;User Id=sa;Password=YourPassword123!;\",\n        \"mssql-mcp:latest\"\n      ]\n    }\n  }\n}\n```\n\n#### Scenario 2: SQL Server in Another Docker Container\n\n**Solution**: Use Docker Compose with a custom network and reference containers by service name.\n\n```yaml\nversion: '3.8'\nnetworks:\n  sql-network:\n    driver: bridge\n\nservices:\n  mssql-mcp:\n    build: .\n    environment:\n      # Use the service name 'sqlserver' as the hostname\n      - MSSQL_CONNECTION_STRING=Server=sqlserver;Database=MyDatabase;User Id=sa;Password=YourPassword123!;\n    stdin_open: true\n    tty: true\n    networks:\n      - sql-network\n    depends_on:\n      - sqlserver\n      \n  sqlserver:\n    image: mcr.microsoft.com/mssql/server:2022-latest\n    environment:\n      - ACCEPT_EULA=Y\n      - SA_PASSWORD=YourPassword123!\n    networks:\n      - sql-network\n    ports:\n      - \"1433:1433\"  # Expose to host for external tools\n```\n\n#### Scenario 3: Linux with Host Network Mode\n\n**Linux Only Solution**: Use Docker's host networking mode for direct host network access.\n\n```bash\n# Linux only - shares the host's network stack\ndocker run -it --rm --network host \\\n  -e MSSQL_CONNECTION_STRING=\"Server=localhost;Database=MyDB;User Id=sa;Password=YourPassword123!;\" \\\n  mssql-mcp:latest\n```\n\n### Platform-Specific Considerations\n\n| Platform | host.docker.internal | Host Network Mode | Recommended Solution |\n|----------|---------------------|-------------------|---------------------|\n| **Windows** | ✅ Works out of box | ❌ Not supported | Use `host.docker.internal` |\n| **macOS** | ✅ Works out of box | ❌ Not supported | Use `host.docker.internal` |\n| **Linux** | ⚠️ Requires `--add-host` | ✅ Supported | Use `--network host` or `host.docker.internal` |\n\n**Linux `host.docker.internal` setup:**\n```bash\ndocker run -it --rm \\\n  --add-host=host.docker.internal:host-gateway \\\n  -e MSSQL_CONNECTION_STRING=\"Server=host.docker.internal;Database=MyDB;User Id=sa;Password=YourPassword123!;\" \\\n  mssql-mcp:latest\n```\n\n### Testing Network Connectivity\n\nTo verify your container can reach the SQL Server:\n\n```bash\n# Test from inside a running container\ndocker exec -it \u003ccontainer_name\u003e ping host.docker.internal\n\n# Test SQL Server port specifically\ndocker run --rm -it mcr.microsoft.com/mssql-tools \\\n  /bin/bash -c \"sqlcmd -S host.docker.internal -U sa -P 'YourPassword123!' -Q 'SELECT @@VERSION'\"\n```\n\n### Common Networking Troubleshooting\n\n1. **Connection Refused**: \n   - Verify SQL Server is listening on all interfaces: `netstat -an | grep 1433`\n   - Check Windows Firewall allows Docker subnet access\n\n2. **DNS Resolution**:\n   - Test: `docker run --rm busybox nslookup host.docker.internal`\n   - Ensure Docker Desktop is running (for Windows/macOS)\n\n3. **Container-to-Container**:\n   - Verify both containers are on the same Docker network\n   - Use container service names, not localhost\n\n4. **Port Conflicts**:\n   - Ensure port 1433 isn't already bound by another process\n   - Check with: `netstat -tlnp | grep 1433`\n\n## Usage Examples\n\nOnce configured, AI agents can use natural language to interact with your database:\n\n**\"Show me all the tables in the database\"**\n→ Uses `list_tables` tool\n\n**\"Describe the structure of the Users table\"**\n→ Uses `execute_sql` with an INFORMATION_SCHEMA query\n\n**\"Find all users created in the last 30 days\"**\n→ Uses `execute_sql` with appropriate SELECT query\n\n**\"Create a new customer record\"**\n→ Uses `execute_sql` with INSERT statement\n\n## Security Considerations\n\n### ⚠️ Important Security Warnings\n\n- **Database Permissions**: Only grant the minimum required permissions to the database user\n- **Connection Security**: Use encrypted connections for production environments\n- **Access Control**: This MCP server provides full SQL execution capabilities - ensure proper access controls\n- **Audit Logging**: Consider enabling SQL Server audit logging for production use\n- **Network Security**: Restrict network access to the database server appropriately\n\n### Recommended Database Permissions\n\nFor read-only access:\n```sql\n-- Create a dedicated user with minimal permissions\nCREATE LOGIN mcp_readonly WITH PASSWORD = 'SecurePassword123!';\nCREATE USER mcp_readonly FOR LOGIN mcp_readonly;\n\n-- Grant only necessary permissions\nGRANT SELECT ON SCHEMA::dbo TO mcp_readonly;\nGRANT VIEW DEFINITION ON SCHEMA::dbo TO mcp_readonly;\n```\n\nFor read-write access:\n```sql\n-- Create a dedicated user\nCREATE LOGIN mcp_readwrite WITH PASSWORD = 'SecurePassword123!';\nCREATE USER mcp_readwrite FOR LOGIN mcp_readwrite;\n\n-- Grant necessary permissions\nGRANT SELECT, INSERT, UPDATE, DELETE ON SCHEMA::dbo TO mcp_readwrite;\nGRANT VIEW DEFINITION ON SCHEMA::dbo TO mcp_readwrite;\n```\n\n## Troubleshooting\n\n### Connection Issues\n\n1. **Verify connection string**: Test with SQL Server Management Studio or Azure Data Studio\n2. **Check firewall**: Ensure SQL Server port (default 1433) is accessible\n3. **Enable TCP/IP**: Ensure TCP/IP protocol is enabled in SQL Server Configuration Manager\n4. **Authentication mode**: Verify SQL Server is configured for the appropriate authentication mode\n\n### Container Issues\n\n1. **Network connectivity**: Use `host.docker.internal` instead of `localhost` when connecting from container to host\n2. **Environment variables**: Ensure the connection string is properly escaped in Docker commands\n3. **Logs**: Check container logs with `docker logs \u003ccontainer_id\u003e`\n\n## License\n\nThis 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.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## Architecture\n\n- **[Akka.NET](https://getakka.net/)**: Used for internal actor system coordination and database validation\n- **[MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk)**: Official Model Context Protocol implementation\n- **Microsoft.Data.SqlClient**: High-performance SQL Server connectivity\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronontheweb%2Fmssql-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronontheweb%2Fmssql-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronontheweb%2Fmssql-mcp/lists"}