SQL Server MCP Server for Claude Code

A Machine Comprehension Protocol (MCP) server that enables Claude Code to directly query Microsoft SQL Server databases.

Credits

This project is based on mssql_mcp_server by Richard Han. It has been adapted to use FreeTDS for improved cross-platform compatibility.

Prerequisites

• Python 3.8 or higher
• FreeTDS (installed by the setup script)
• SQL Server instance accessible from your machine
• One of the following operating systems:
  • Linux (Ubuntu, Debian, RedHat, CentOS, etc.)
  • macOS
  • Windows (via WSL - Windows Subsystem for Linux)

Installation

1. Clone or download this repository:

   git clone https://github.com/your-username/mcp-server-for-sql.git
   cd mcp-server-for-sql
   

2. Run the installation script:

   ./install_mssql_mcp_clean.sh
   

   This script will:

   • Detect your operating system
   • Check Python installation
   • Install FreeTDS
   • Create necessary MCP server scripts
   • Set up configuration files

3. Configure SQL Server connection:

   ./configure_mcp.sh
   

   You'll be prompted to enter:

   • SQL Server hostname/IP and port (e.g., "myserver.database.azure.com,1433")
   • Database name
   • Username
   • Password

4. Test the connection:

   ./test_tsql.sh
   

   This will verify that your connection details are correct and FreeTDS is working properly.

Usage with Claude Code

Once installed and configured, you can use the SQL Server MCP integration in Claude Code with:

mcp__mssql__execute_sql(query="SELECT * FROM YourTable")

Examples:

• List all tables: mcp__mssql__execute_sql(query="SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE='BASE TABLE'")
• Count records: mcp__mssql__execute_sql(query="SELECT COUNT(*) AS Count FROM YourTable")
• Query with filtering: mcp__mssql__execute_sql(query="SELECT * FROM Customers WHERE City='London'")

How It Works Behind the Scenes

MCP Architecture

1. Configuration Setup:

   • The .mcp.json file defines the MCP server configuration
   • It specifies how Claude Code should launch and communicate with the server
   • Contains connection details for your SQL Server

2. Claude Code Integration:

   • When you start Claude Code in the project directory, it detects the .mcp.json file
   • It registers the mcp__mssql__execute_sql tool for use in your session

3. Query Execution Flow:

   When you run a query:

   1. You type: mcp__mssql__execute_sql(query="SELECT * FROM Customers")

   2. Claude sends a request to the MCP server:

      {
        "requestId": "123",
        "type": "CallToolRequest",
        "toolName": "execute_sql",
        "callId": "456",
        "parameters": {
          "query": "SELECT * FROM Customers"
        }
      }
      

   3. The MCP server:

      • Creates a temporary SQL file with your query
      • Executes it using FreeTDS's tsql utility
      • Parses the results into a structured format
      • Cleans up temporary files

   4. The server returns results to Claude:

      {
        "requestId": "123",
        "type": "CallToolResponse",
        "callId": "456",
        "result": {
          "rows": [
            {"CustomerID": "1", "Name": "John", "...": "..."},
            {"CustomerID": "2", "Name": "Jane", "...": "..."}
          ]
        }
      }
      

   5. Claude formats and displays the results in your conversation

Technical Implementation

• FreeTDS Integration: Uses the FreeTDS tsql command-line tool to connect to SQL Server, providing broad compatibility across platforms
• Security: Database credentials are stored only in your local configuration file, never sent as part of prompts
• Error Handling: SQL errors are captured and returned as structured responses
• Temporary File Management: Creates and cleans up temporary SQL files for each query

File Structure

• install_mssql_mcp_clean.sh - Main installation script
• mssql_mcp_server.py - Core MCP server implementation
• run_mssql_mcp.py - Launcher script
• configure_mcp.sh - Connection configuration script
• test_tsql.sh - Connection testing script
• .mcp.json - MCP configuration file (created during setup)

Troubleshooting

Connection Issues

1. Check FreeTDS installation:

   tsql -C
   

   Should display FreeTDS version information.

2. Verify SQL Server accessibility:

   • Ensure your firewall allows connections to the SQL Server port (typically 1433)
   • Check that the SQL Server allows remote connections
   • Verify your username and password are correct

3. Check connection configuration:

   • Run ./configure_mcp.sh to update your connection details
   • Make sure server address includes the port (e.g., "server,1433")

MCP Server Issues

1. Check log output: When running Claude Code, check the terminal for any error messages from the MCP server.

2. Verify .mcp.json file: Ensure it contains the correct paths and environment variables.

3. Test direct execution:

   python3 run_mssql_mcp.py
   

   The server should start without errors.

WSL-Specific Issues (Windows)

1. Python and FreeTDS setup:

   sudo apt update
   sudo apt install -y python3-dev python3-pip freetds-bin freetds-dev
   

2. Connecting to Windows SQL Server from WSL:

   • Use host.docker.internal or your Windows IP address as the server address
   • Ensure Windows Firewall allows connections on port 1433

3. Temporary file issues: If you experience problems with temporary files in WSL, make sure the temp directory exists and is writable.

Advanced Configuration

Manual Editing of .mcp.json

You can directly edit the .mcp.json file to:

• Change the Python executable path
• Modify environment variables
• Add additional configuration options

Example:

{
  "mcpServers": {
    "mssql": {
      "type": "stdio",
      "command": "python3",
      "args": ["/path/to/run_mssql_mcp.py"],
      "env": {
        "MSSQL_SERVER": "myserver.database.windows.net,1433",
        "MSSQL_DATABASE": "mydatabase",
        "MSSQL_USER": "myusername",
        "MSSQL_PASSWORD": "mypassword"
      }
    }
  }
}

Security Considerations

• Use a database account with minimal necessary permissions
• Consider using integrated security if available in your environment
• Keep your .mcp.json file secure as it contains database credentials
• Regularly review and update credentials

License

This project is open-source and freely available for use and modification.

Contributions

Contributions, bug reports, and feature requests are welcome! Please feel free to submit issues or pull requests to the original repository by Richard Han: mssql_mcp_server.