SQL Server MCP Server for Claude

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with Microsoft SQL Server databases on Windows using secure Windows Authentication.

🌟 Features

• Secure Windows Authentication - Uses your Windows credentials (no passwords stored)
• Read-Only by Default - Safe SELECT queries without risk of data modification
• Controlled Write Access - Separate tool for INSERT/UPDATE/DELETE operations
• Safety Guards - Blocks dangerous operations like DROP and TRUNCATE
• Result Limiting - Prevents overwhelming responses with configurable row limits
• Comprehensive Logging - Detailed logs for troubleshooting

📋 Prerequisites

• Windows OS (Windows 10/11 or Windows Server)
• Python 3.10 or higher
• SQL Server (Express, Standard, or Enterprise edition)
• ODBC Driver 17 for SQL Server - Download here
• Claude Desktop - Download here

🚀 Quick Start

1. Clone or Download

git clone https://github.com/yourusername/sql-server-mcp.git
cd sql-server-mcp

Or download and extract the ZIP file to C:\MCP-SQLServer\

2. Install ODBC Driver

If not already installed, download and install ODBC Driver 17 for SQL Server from Microsoft.

3. Create Virtual Environment

cd C:\MCP-SQLServer
python -m venv venv
venv\Scripts\activate

4. Install Dependencies

pip install -r requirements.txt

5. Configure Claude Desktop

Edit the Claude Desktop configuration file:

C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json

Add this configuration (adjust paths and database details as needed):

{
  "mcpServers": {
    "mssql": {
      "command": "C:\\MCP-SQLServer\\venv\\Scripts\\python.exe",
      "args": [
        "C:\\MCP-SQLServer\\server.py"
      ],
      "env": {
        "MSSQL_SERVER": "localhost\\SQLEXPRESS",
        "MSSQL_DATABASE": "YourDatabaseName",
        "MSSQL_WINDOWS_AUTH": "true",
        "MSSQL_DRIVER": "{ODBC Driver 17 for SQL Server}"
      }
    }
  }
}

Important: Use double backslashes (\\) in all Windows paths!

6. Restart Claude Desktop

1. Completely close Claude Desktop (check system tray)
2. Reopen Claude Desktop
3. The MCP server will connect automatically

7. Test It!

Try these commands in Claude:

List all tables in my database

Describe the structure of MyTable

Show me the first 10 rows from MyTable

🛠️ Available Tools

The MCP server provides these tools to Claude:

Tool	Description	Safety
list_tables	Lists all tables in the database	Read-only ✅
describe_table	Shows column details and schema	Read-only ✅
execute_query	Runs SELECT queries	Read-only ✅
get_table_count	Gets row count for a table	Read-only ✅
execute_write_query	Runs INSERT/UPDATE/DELETE	Requires explicit use ⚠️

🔧 Configuration Options

Configure the server using environment variables in the Claude Desktop config:

Variable	Description	Default
MSSQL_SERVER	SQL Server instance name	localhost\SQLEXPRESS
MSSQL_DATABASE	Database name	GeminiUsageTracking
MSSQL_WINDOWS_AUTH	Use Windows Authentication	true
MSSQL_DRIVER	ODBC driver to use	{ODBC Driver 17 for SQL Server}
MSSQL_USER	SQL username (if not using Windows Auth)	-
MSSQL_PASSWORD	SQL password (if not using Windows Auth)	-

SQL Server Authentication (Alternative)

If you prefer SQL Server authentication instead of Windows authentication:

{
  "mcpServers": {
    "mssql": {
      "command": "C:\\MCP-SQLServer\\venv\\Scripts\\python.exe",
      "args": ["C:\\MCP-SQLServer\\server.py"],
      "env": {
        "MSSQL_SERVER": "localhost\\SQLEXPRESS",
        "MSSQL_DATABASE": "YourDatabase",
        "MSSQL_WINDOWS_AUTH": "false",
        "MSSQL_USER": "your_username",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_DRIVER": "{ODBC Driver 17 for SQL Server}"
      }
    }
  }
}

🔍 Example Usage

List All Tables

Claude, can you list all the tables in my database?

Query Data

Show me all records from the Users table where Status = 'Active'

Get Statistics

How many rows are in the Orders table?

Analyze Schema

What's the structure of the Products table?

Safe Updates (with confirmation)

Update the Status to 'Completed' for Order ID 12345

🐛 Troubleshooting

Error: "ODBC Driver not found"

Solution: Install ODBC Driver 17 for SQL Server

Error: "Login failed"

Solution:

• Verify SQL Server is running
• Check that your Windows user has database access
• Try opening SQL Server Management Studio with the same credentials

Error: "Server not found"

Solution:

• Confirm SQL Server instance name: localhost\SQLEXPRESS or localhost\MSSQLSERVER
• Check SQL Server is running in Services (services.msc)
• Enable TCP/IP protocol in SQL Server Configuration Manager

MCP Server not appearing in Claude

Solution:

• Verify config file path is correct
• Ensure you used double backslashes (\\) in all paths
• Check Python virtual environment path is correct
• Restart Claude Desktop completely

Check Logs

View detailed error messages in:

C:\MCP-SQLServer\mssql_mcp.log

🔒 Security Features

✅ Windows Authentication - No passwords stored in configuration files

✅ Read-Only Default - SELECT queries work without risk

✅ Controlled Writes - INSERT/UPDATE/DELETE require explicit tool usage

✅ Dangerous Operation Blocks - DROP and TRUNCATE statements are prevented

✅ Row Limits - Query results limited to 100 rows by default (configurable)

✅ Comprehensive Logging - All operations logged for audit purposes

📝 Files

sql-server-mcp/
├── server.py              # Main MCP server implementation
├── requirements.txt       # Python dependencies
├── README.md             # This file
├── SETUP_INSTRUCTIONS.md # Detailed setup guide
└── .gitignore           # Git ignore patterns

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Built using Model Context Protocol by Anthropic
• Uses pyodbc for SQL Server connectivity

📞 Support

• Issues: GitHub Issues
• Documentation: MCP Documentation
• SQL Server Help: Microsoft SQL Server Docs

⚠️ Disclaimer

This tool provides Claude with direct access to your database. Always:

• Test in a development environment first
• Review queries before execution
• Maintain regular backups
• Follow your organization's security policies
• Use appropriate database user permissions

---

Made with ❤️ for the Claude and SQL Server community