mssql-mcp

MertcanYuzer/mssql-mcp

3.2

If you are the rightful owner of mssql-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server for Microsoft SQL Server with dynamic connection handling.

Tools
6
Resources
0
Prompts
0

MSSQL MCP Server

A Model Context Protocol (MCP) server for Microsoft SQL Server with dynamic connection handling. Unlike other SQL MCP servers, this implementation doesn't rely on environment variables for database connections, allowing you to connect to multiple databases dynamically.

Features

  • Dynamic Connection Management: Connect to multiple MSSQL databases without environment variables
  • Connection Pooling: Efficient connection management with built-in pooling
  • Secure Authentication: Support for encrypted connections and certificate validation
  • Query Execution: Execute SQL queries with parameter support
  • Schema Exploration: List tables and describe table structures
  • Multiple Active Connections: Manage multiple database connections simultaneously

Installation & Build

Prerequisites

  • Node.js 18+
  • pnpm (or npm/yarn)

Clone and Build

# Clone the repository
git clone <your-repo-url> mssql-mcp
cd mssql-mcp

# Install dependencies
pnpm install

# Build the project
pnpm build

# Note your project path (you'll need this for configuration)
pwd

Building Standalone Executables

You can package the MCP server as a standalone executable using Fossilize:

# Build executable using your local Node.js version
pnpm compile

# Build using LTS Node.js version
pnpm compile:lts

# Build using latest Node.js version
pnpm compile:latest

# Or use fossilize directly with custom options
npx fossilize dist/index.js

Fossilize creates platform-specific executables in the project root:

  • mssql-mcp-linux-x64 (Linux)
  • mssql-mcp-darwin-x64 (macOS Intel)
  • mssql-mcp-darwin-arm64 (macOS Apple Silicon)
  • mssql-mcp-win32-x64.exe (Windows)

The executables can be distributed and run without Node.js installation.

IDE Configuration

You can configure the MCP server in two ways:

  1. Using Node.js (requires Node.js installed)
  2. Using Standalone Executable (no Node.js required)

Claude Code

Using Node.js:
# Simple one-line command
claude mcp add mssql-server node /path/to/mssql-mcp/dist/index.js
Using Standalone Executable:
# For Linux
claude mcp add mssql-server /path/to/mssql-mcp/mssql-mcp-linux-x64

# For macOS Intel
claude mcp add mssql-server /path/to/mssql-mcp/mssql-mcp-darwin-x64

# For macOS Apple Silicon
claude mcp add mssql-server /path/to/mssql-mcp/mssql-mcp-darwin-arm64

# For Windows
claude mcp add mssql-server C:/path/to/mssql-mcp/mssql-mcp-win32-x64.exe

For WSL2 users:

# Get your project path in WSL2
pwd  # Example output: /mnt/c/repos/mssql-mcp

# Add to Claude Code (Node.js version)
claude mcp add mssql-server node /mnt/c/repos/mssql-mcp/dist/index.js

# Or using executable
claude mcp add mssql-server /mnt/c/repos/mssql-mcp/mssql-mcp-linux-x64

Cursor

Add to Cursor settings (File → Preferences → Settings → MCP):

Using Node.js:
{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["/path/to/mssql-mcp/dist/index.js"]
    }
  }
}
Using Standalone Executable:
{
  "mcpServers": {
    "mssql": {
      "command": "/path/to/mssql-mcp/mssql-mcp-linux-x64"
    }
  }
}

Claude Desktop

Add to Claude Desktop configuration file:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
Using Node.js:
{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["/path/to/mssql-mcp/dist/index.js"]
    }
  }
}
Using Standalone Executable:
{
  "mcpServers": {
    "mssql": {
      "command": "/path/to/mssql-mcp/mssql-mcp-linux-x64"
    }
  }
}

For Windows executable:

{
  "mcpServers": {
    "mssql": {
      "command": "C:/path/to/mssql-mcp/mssql-mcp-win32-x64.exe"
    }
  }
}

Windsurf

Add to Windsurf settings:

{
  "mcp.servers": {
    "mssql": {
      "command": "node",
      "args": ["/path/to/mssql-mcp/dist/index.js"]
    }
  }
}

VS Code (with MCP extension)

Add to VS Code settings.json:

{
  "mcp.servers": {
    "mssql": {
      "command": "node",
      "args": ["/path/to/mssql-mcp/dist/index.js"]
    }
  }
}

AugmentCode

Add to AugmentCode MCP configuration:

{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["/path/to/mssql-mcp/dist/index.js"]
    }
  }
}

Platform-Specific Notes

Windows

Use full paths with forward slashes:

"args": ["C:/Users/username/projects/mssql-mcp/dist/index.js"]

Windows + WSL2

When running the IDE on Windows but the MCP server in WSL2:

{
  "command": "wsl",
  "args": ["node", "/home/username/mssql-mcp/dist/index.js"]
}

When running the IDE inside WSL2:

{
  "command": "node",
  "args": ["/home/username/mssql-mcp/dist/index.js"]
}

macOS & Linux

Use absolute paths:

"args": ["/home/username/mssql-mcp/dist/index.js"]

Available Tools

1. connect

Connect to an MSSQL database:

{
  "connectionId": "mydb",
  "server": "localhost",
  "port": 1433,
  "database": "mydatabase",
  "user": "sa",
  "password": "yourpassword",
  "encrypt": true,
  "trustServerCertificate": false
}

2. query

Execute SQL queries:

{
  "connectionId": "mydb",
  "query": "SELECT * FROM users WHERE age > @age",
  "parameters": {
    "age": 18
  }
}

3. listTables

List all tables:

{
  "connectionId": "mydb",
  "schema": "dbo"
}

4. describeTable

Get table schema:

{
  "connectionId": "mydb",
  "tableName": "users",
  "schema": "dbo"
}

5. listConnections

List active connections:

{}

6. disconnect

Close a connection:

{
  "connectionId": "mydb"
}

SQL Server Connection Tips

From WSL2 to Windows SQL Server

{
  "server": "host.docker.internal",  // or use: $(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
  "port": 1433,
  "encrypt": false,
  "trustServerCertificate": true
}

Local SQL Server

{
  "server": "localhost",
  "port": 1433
}

Azure SQL Database

{
  "server": "your-server.database.windows.net",
  "port": 1433,
  "encrypt": true
}

Development

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Run built version
pnpm start

Troubleshooting

Test the MCP server directly

Using Node.js:
node /path/to/mssql-mcp/dist/index.js
# Should output: "MSSQL MCP server running on stdio"
Using Executable:
# Linux
/path/to/mssql-mcp/mssql-mcp-linux-x64
# Should output: "MSSQL MCP server running on stdio"

# macOS
/path/to/mssql-mcp/mssql-mcp-darwin-x64  # or mssql-mcp-darwin-arm64
# Should output: "MSSQL MCP server running on stdio"

# Windows
C:\path\to\mssql-mcp\mssql-mcp-win32-x64.exe
# Should output: "MSSQL MCP server running on stdio"

Common Issues

  1. "Connection refused": Check if SQL Server is running and accepting TCP/IP connections
  2. "Login failed": Verify SQL Server authentication mode (should be mixed mode)
  3. "Network error": Check firewall settings and SQL Server network configuration
  4. WSL2 clock sync: Run sudo hwclock -s if you get SSL/TLS errors
  5. Executable permissions (Linux/macOS): If executable won't run, ensure it has execute permissions: 
    chmod +x /path/to/mssql-mcp/mssql-mcp-linux-x64  # or mssql-mcp-darwin-x64/arm64
  6. macOS security: On macOS, you may need to allow the executable in System Preferences > Security & Privacy

made with claude code