EvilPhatBoi/McpSqlServer

MSSQL MCP Server

A Model Context Protocol (MCP) server that enables LLMs like Claude to interact with Microsoft SQL Server databases through natural language.

Features

• 🔍 Query your SQL Server database using natural language
• 📊 Read, insert, update, and delete data
• 🏗️ Create and manage tables and indexes
• 🔒 Secure connection handling with optional read-only mode
• ⚡ Direct TypeScript execution with tsx - no build step required

Quick Start

Option 1: Use directly from GitHub with npx (Recommended)

No installation needed! Just configure Claude Desktop:

Windows

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "mssql": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "github:EvilPhatBoi/McpSqlServer"],
      "env": {
        "SERVER_NAME": "your-server.database.windows.net",
        "DATABASE_NAME": "your-database",
        "SQL_USERNAME": "your-username",
        "SQL_PASSWORD": "your-password",
        "PORT": "1433",
        "ENCRYPT": "true",
        "TRUST_SERVER_CERTIFICATE": "false",
        "CONNECTION_TIMEOUT": "30",
        "READONLY": "false"
      }
    }
  }
}

macOS/Linux

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mssql": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:EvilPhatBoi/McpSqlServer"],
      "env": {
        "SERVER_NAME": "your-server.database.windows.net",
        "DATABASE_NAME": "your-database",
        "SQL_USERNAME": "your-username",
        "SQL_PASSWORD": "your-password",
        "PORT": "1433",
        "ENCRYPT": "true",
        "TRUST_SERVER_CERTIFICATE": "false",
        "CONNECTION_TIMEOUT": "30",
        "READONLY": "false",
        "DEBUG": "false"
      }
    }
  }
}

Note for legacy SQL Servers: If you experience SSL/TLS connection issues with older SQL Server versions, try:

• "ENCRYPT": "false" to disable TLS/SSL encryption
• "TRUST_SERVER_CERTIFICATE": "true" to trust self-signed certificates
• "CONNECTION_TIMEOUT": "60" or higher for slower connections
• "DEBUG": "true" to see detailed connection logs

Option 2: Clone and run locally

1. Clone the repository:

git clone https://github.com/EvilPhatBoi/McpSqlServer.git
cd McpSqlServer

2. Install dependencies:

npm install

3. Create .env file:

cp .env.example .env
# Edit .env with your database credentials

4. Configure Claude Desktop to point to your local installation:

{
  "mcpServers": {
    "mssql": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "C:/path/to/McpSqlServer/src/index.ts"],
      "env": {
        "SERVER_NAME": "your-server.database.windows.net",
        "DATABASE_NAME": "your-database",
        "SQL_USERNAME": "your-username",
        "SQL_PASSWORD": "your-password"
      }
    }
  }
}

Environment Variables

Usage Examples

Once configured, you can interact with your database using natural language in Claude:

• "Show me all customers from New York"
• "Create a table called products with columns for id, name, and price"
• "Update the price of product with id 5 to 29.99"
• "List all tables in the database"
• "Describe the structure of the orders table"

Development

Running locally with tsx:

npm run start  # Run the server
npm run dev    # Run with watch mode

Type checking:

npm run typecheck

Security Notes

• Never commit .env files with real credentials
• Use read-only mode (READONLY=true) in production for safety
• The server requires WHERE clauses for updates to prevent accidental mass updates
• Consider using environment-specific credentials

Troubleshooting

Connection issues

• Ensure your SQL Server allows remote connections
• Check firewall rules for SQL Server port (default 1433, or your custom PORT setting)
• Verify credentials and server name
• Enable debug logging by setting DEBUG=true in your environment variables

SSL/TLS connection issues

• For older SQL Server versions that don't support modern TLS, set ENCRYPT=false
• If using self-signed certificates, set TRUST_SERVER_CERTIFICATE=true
• For connection timeout issues, increase CONNECTION_TIMEOUT to 60 or higher
• Check that your SQL Server accepts the TLS version your Node.js supports

Debug mode

To enable detailed logging for troubleshooting:

"env": {
  "DEBUG": "true",
  // ... other environment variables
}

Authentication errors

• This server uses SQL authentication, not Windows authentication
• Ensure SQL authentication is enabled on your server
• Check that the SQL user has appropriate permissions

License

MIT