davisdane2/mssql-mcp-vscode-extratools

MSSQL MCP Server

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

Overview

This MCP server allows AI assistants like Claude to connect to and query Microsoft SQL Server databases seamlessly. Ask questions in plain English and get instant results from your database - no SQL knowledge required!

Quick Example

You: "Show me all customers from New York"
Claude: *queries your SQL Server database and returns the results in plain English*

Features

The Model Context Protocol (MCP) is a standardized protocol that enables AI assistants to communicate with external systems. This server implements MCP to provide secure, controlled access to SQL Server databases.

Capabilities

• Natural Language Queries: Ask questions in plain English and get SQL Server results
• Full CRUD Operations: Create, read, update, and delete data through conversational commands
• Schema Management: Manage tables, indexes, and database structures
• Secure Authentication: Support for both SQL authentication and Azure Active Directory
• Read-Only Mode: Optional safety mode to prevent accidental data modifications
• Connection Security: Configurable timeouts and SSL/TLS support

Quick Start

Prerequisites

• Node.js 16 or higher (tested with v22.18.0)
• Microsoft SQL Server (local instance, SQL Express, or remote server)
• Claude Desktop, VS Code with Agent extension, or other MCP-compatible AI assistant

Installation

1. Clone the Repository

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

2. Install Dependencies

   npm install
   

3. Build the Project

   npm run build
   

Configuration Setup

Option 1: VS Code Agent Setup

1. Install VS Code Agent Extension

   • Open VS Code
   • Go to Extensions (Ctrl+Shift+X or Cmd+Shift+X)
   • Search for "Agent" and install the official Agent extension

2. Create MCP Configuration File

   Create a .vscode/mcp.json file in your workspace:

   {
     "servers": {
       "mssql": {
          "type": "stdio",
          "command": "node",
          "args": ["/absolute/path/to/mssql-mcp-server/dist/index.js"],
          "env": {
            "SERVER_NAME": "localhost",
            "DATABASE_NAME": "your-database-name",
            "READONLY": "false"
          }
        }
      }
   }
   

3. Alternative: User Settings Configuration

   You can also configure this globally in VS Code settings:

   • Open Settings (Ctrl+, or Cmd+,)
   • Search for "mcp"
   • Click "Edit in settings.json"
   • Add the configuration:

   {
     "mcp": {
       "servers": {
         "mssql": {
           "command": "node",
           "args": ["/absolute/path/to/mssql-mcp-server/dist/index.js"],
           "env": {
             "SERVER_NAME": "localhost",
             "DATABASE_NAME": "your-database-name",
             "READONLY": "false"
           }
         }
       }
     }
   }
   

4. Restart VS Code

   • Close and reopen VS Code for the changes to take effect

5. Verify MCP Server

   • Open Command Palette (Ctrl+Shift+P)
   • Run "MCP: List Servers" to verify your server is configured
   • You should see "mssql" in the list of available servers

Option 2: Claude Desktop Setup

1. Locate Claude Desktop Configuration

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

   Or use the built-in menu: Settings → Developer → Edit Config

2. Add MCP Server Configuration

   Add the server to your claude_desktop_config.json:

   {
     "mcpServers": {
       "mssql": {
         "command": "node",
         "args": ["/absolute/path/to/mssql-mcp-server/dist/index.js"],
         "env": {
           "SERVER_NAME": "localhost",
           "DATABASE_NAME": "your-database-name",
           "READONLY": "false"
         }
       }
     }
   }
   

3. Restart Claude Desktop

   • Completely quit and reopen Claude Desktop to load the new configuration

Configuration Parameters

Authentication

The server supports multiple authentication methods:

Windows Authentication (default for local SQL Server):

• Uses your current Windows credentials
• No additional configuration needed for local instances
• Most common for SQL Express and local development

Azure Active Directory (for Azure SQL):

• Requires @azure/identity package (included)
• Login via Azure CLI: az login
• Useful for Azure SQL Database connections

SQL Server Authentication:

• Username/password authentication
• May require source code modifications to pass credentials securely
• Not recommended - use Windows Auth or Azure AD when possible

Usage Examples

Once configured, interact with your database using natural language:

"Show me all users from New York"
"Create a new table called products with columns for id, name, and price"
"Update all pending orders to completed status"
"List all tables in the database"
"What's the total revenue for last month?"

Security & Best Practices

• WHERE Clause Required: Read operations require WHERE clauses to prevent accidental full table scans
• Update Protection: Update and delete operations require explicit WHERE clauses
• Read-Only Mode: Set READONLY: "true" in production environments when modification access isn't needed
• Azure AD Authentication: Uses secure Azure Active Directory authentication by default
• Connection Encryption: Supports SSL/TLS for encrypted connections

Sample Configurations

Example configuration files are available in src/samples/:

• claude_desktop_config.json - Claude Desktop configuration template
• vscode_agent_config.json - VS Code Agent configuration template

Tested Environments

This MCP server has been tested and verified with:

SQL Server Versions:

• SQL Server 2025
• SQL Server Express 13
• Local SQL Server instances on Windows Server 2012

Development Tools:

• JetBrains DataGrip
• SQL Server Management Studio 2021
• VS Code with Agent extension

AI Assistants:

• Claude Desktop
• Claude Code (VS Code)
• Gemini CLI

Runtime:

• Node.js v22.18.0
• Python 3.13

Operating Systems:

• Windows 11 Enterprise Preview
• Windows Server 2012

Advanced Configuration

Enabling EXEC Tools (Use with Caution)

By default, stored procedure execution is restricted for security. To enable EXEC tools:

1. Review the files in the ALLOW_EXECUTE/ directory
2. Carefully evaluate the security implications for your environment
3. Copy the necessary files to src/tools/ only if you trust the stored procedures being executed

Security Warning: Only enable EXEC tools if you fully understand and trust the stored procedures in your database.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Acknowledgments

This project builds upon excellent work from the community:

• MSSQLMCP_DBA by oflindall - Additional DBA tools
• Azure SQL-AI-samples - Original Azure samples
• How to Connect AI Assistant to SQL - Setup guide inspiration

License

MIT License - see LICENSE file for details

Support

For issues, questions, or contributions, please open an issue on GitHub.