SQL Server Pro MCP server

The Microsoft SQL Server MCP server provides a comprehensive interface for AI assistants and language models to interact with MSSQL databases, enabling schema inspection, query execution, and management of database objects through a standardized protocol.

Features

Complete Database Schema Traversal

• 23 comprehensive database management tools
• Full database object hierarchy exploration
• Advanced database object management
• Intelligent resource access
• Large content handling without truncation

Core Capabilities

• Database connection with flexible authentication
• Schema inspection for complete database exploration
• Query execution for SELECT, INSERT, UPDATE, DELETE, and DDL
• Comprehensive stored procedure management
• View and index management
• Resource access for tables and views

Important Usage Guidelines

Database Limitation

CRITICAL: Limit to ONE database per MCP server instance

• Each MCP server creates 23 tools per database
• Cursor has a 40-tool limit across all MCP servers
• For multiple databases, use separate MCP server instances in different projects

Large Content Limitations

IMPORTANT: File operations not supported within chat context

• Large stored procedures can be retrieved and viewed in chat
• Saving large content to files via MCP tools is not reliable due to token limits
• For bulk data extraction: Use standalone Python scripts with direct database connections

Installation

Prerequisites

• Python 3.10 or higher
• ODBC Driver 17 for SQL Server
• Access to an MSSQL Server instance

Quick Setup

1. Clone or create the project directory:

   mkdir mcp-sqlserver && cd mcp-sqlserver
   

2. Run the installation script:

   chmod +x install.sh
   ./install.sh
   

3. Configure your database connection:

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

Manual Installation

1. Create virtual environment:

   python3 -m venv venv
   source venv/bin/activate
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Install ODBC Driver (macOS):

   brew tap microsoft/mssql-release
   brew install msodbcsql17 mssql-tools
   

Configuration

Create a .env file with your database configuration:

MSSQL_DRIVER={ODBC Driver 17 for SQL Server}
MSSQL_SERVER=your-server-address
MSSQL_DATABASE=your-database-name
MSSQL_USER=your-username
MSSQL_PASSWORD=your-password
MSSQL_PORT=1433
TrustServerCertificate=yes

Configuration Options

• MSSQL_SERVER: Server hostname or IP address (required)
• MSSQL_DATABASE: Database name to connect to (required)
• MSSQL_USER: Username for authentication
• MSSQL_PASSWORD: Password for authentication
• MSSQL_PORT: Port number (default: 1433)
• MSSQL_DRIVER: ODBC driver name (default: {ODBC Driver 17 for SQL Server})
• TrustServerCertificate: Trust server certificate (default: yes)
• Trusted_Connection: Use Windows authentication (default: no)

Usage

Running the Server

For AI Assistant Integration:

python3 src/server.py

The server will start and wait for MCP protocol messages on stdin. This is how AI assistants like Claude Desktop or other MCP clients will communicate with it.

For Testing and Development:

1. Test database connection:

   python3 test_connection.py
   

2. Check server status:

   ./status.sh
   

Available Tools

Core Database Operations

• read_query - Execute SELECT queries to read data
• write_query - Execute INSERT, UPDATE, DELETE, and DDL queries
• list_tables - List all tables in the database
• describe_table - Get schema information for a specific table
• create_table - Create new tables

Stored Procedure Management

• create_procedure - Create new stored procedures
• modify_procedure - Modify existing stored procedures
• delete_procedure - Delete stored procedures
• list_procedures - List all stored procedures with metadata
• describe_procedure - Get complete procedure definitions
• execute_procedure - Execute procedures with parameters
• get_procedure_parameters - Get detailed parameter information

View Management

• create_view - Create new views
• modify_view - Modify existing views
• delete_view - Delete views
• list_views - List all views in the database
• describe_view - Get view definitions and schema

Index Management

• create_index - Create new indexes
• delete_index - Delete indexes
• list_indexes - List all indexes (optionally by table)
• describe_index - Get detailed index information

Schema Exploration

• list_schemas - List all schemas in the database
• list_all_objects - List all database objects organized by schema

Available Resources

Both tables and views are exposed as MCP resources with URIs like:

• mssql://table_name/data - Access table data in CSV format
• mssql://view_name/data - Access view data in CSV format

Database Schema Traversal Examples

Explore Database Structure

# Start with schemas
list_schemas

# Get all objects in a specific schema
list_all_objects(schema_name: "dbo")

# Or get all objects across all schemas
list_all_objects()

Table Exploration

# List all tables
list_tables

# Get detailed table information
describe_table(table_name: "YourTableName")

# Access table data as MCP resource
# URI: mssql://YourTableName/data

View Management

# List all views
list_views

# Get view definition
describe_view(view_name: "YourViewName")

# Create a new view
create_view(view_script: "CREATE VIEW MyView AS SELECT * FROM MyTable WHERE Active = 1")

# Access view data as MCP resource
# URI: mssql://YourViewName/data

Stored Procedure Operations

# List all procedures
list_procedures

# Get complete procedure definition
describe_procedure(procedure_name: "YourProcedureName")

# Get parameter details
get_procedure_parameters(procedure_name: "YourProcedureName")

# Execute procedure
execute_procedure(procedure_name: "YourProcedureName", parameters: ["param1", "param2"])

Index Management

# List all indexes
list_indexes()

# List indexes for specific table
list_indexes(table_name: "YourTableName")

# Get index details
describe_index(index_name: "IX_YourIndex", table_name: "YourTableName")

# Create new index
create_index(index_script: "CREATE INDEX IX_NewIndex ON MyTable (Column1, Column2)")

Stored Procedure Management Examples

Create a Simple Stored Procedure

CREATE PROCEDURE GetEmployeeCount
AS
BEGIN
    SELECT COUNT(*) AS TotalEmployees FROM Employees
END

Create a Stored Procedure with Parameters

CREATE PROCEDURE GetEmployeesByDepartment
    @DepartmentId INT,
    @MinSalary DECIMAL(10,2) = 0
AS
BEGIN
    SELECT 
        EmployeeId,
        FirstName,
        LastName,
        Salary,
        DepartmentId
    FROM Employees 
    WHERE DepartmentId = @DepartmentId 
    AND Salary >= @MinSalary
    ORDER BY LastName, FirstName
END

Create a Stored Procedure with Output Parameters

CREATE PROCEDURE GetDepartmentStats
    @DepartmentId INT,
    @EmployeeCount INT OUTPUT,
    @AverageSalary DECIMAL(10,2) OUTPUT
AS
BEGIN
    SELECT 
        @EmployeeCount = COUNT(*),
        @AverageSalary = AVG(Salary)
    FROM Employees 
    WHERE DepartmentId = @DepartmentId
END

Modify an Existing Stored Procedure

ALTER PROCEDURE GetEmployeesByDepartment
    @DepartmentId INT,
    @MinSalary DECIMAL(10,2) = 0,
    @MaxSalary DECIMAL(10,2) = 999999.99
AS
BEGIN
    SELECT 
        EmployeeId,
        FirstName,
        LastName,
        Salary,
        DepartmentId,
        HireDate
    FROM Employees 
    WHERE DepartmentId = @DepartmentId 
    AND Salary BETWEEN @MinSalary AND @MaxSalary
    ORDER BY Salary DESC, LastName, FirstName
END

Large Content Handling

How It Works

The server efficiently handles large database objects like stored procedures:

1. Direct Retrieval: Fetches complete content directly from SQL Server
2. No Truncation: Returns full procedure definitions regardless of size
3. Chat Display: Large procedures can be viewed in full within the chat interface

Usage Examples

# Describe a large procedure (gets complete definition)
describe_procedure(procedure_name: "wmPostPurchase")

# Works with procedures of any size (tested with 1400+ line procedures)

Limitations for File Operations

While large procedures can be retrieved and displayed in chat, saving them to files via MCP tools is not reliable due to inference token limits. For bulk data extraction:

• Small procedures: Copy-paste from chat interface
• Large procedures: Use standalone Python scripts with direct database connections

Integration with AI Assistants

Claude Desktop

Add this server to your Claude Desktop configuration:

{
  "mcpServers": {
    "mssql": {
      "command": "python3",
      "args": ["/path/to/mcp-sqlserver/src/server.py"],
      "cwd": "/path/to/mcp-sqlserver",
      "env": {
        "MSSQL_SERVER": "your-server",
        "MSSQL_DATABASE": "your-database",
        "MSSQL_USER": "your-username",
        "MSSQL_PASSWORD": "your-password"
      }
    }
  }
}

Troubleshooting

Common Issues

1. Connection Failed: Check your database server address, credentials, and network connectivity
2. ODBC Driver Not Found: Install Microsoft ODBC Driver 17 for SQL Server
3. Permission Denied: Ensure the database user has appropriate permissions
4. Port Issues: Verify the correct port number and firewall settings
5. Large Content Issues: Large procedures display in chat but cannot be saved to files via MCP tools

Large Content Troubleshooting

If you encounter issues with large content:

1. Copy-paste approach: Use chat interface to view and copy large procedures
2. External scripts: Create standalone Python scripts for bulk data extraction
3. Check memory: Large procedures are handled efficiently by the database connection
4. Verify permissions: Ensure database user can access procedure definitions

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mssql" '{"command":"python3","args":["/path/to/mcp-sqlserver/src/server.py"],"cwd":"/path/to/mcp-sqlserver","env":{"MSSQL_SERVER":"your-server","MSSQL_DATABASE":"your-database","MSSQL_USER":"your-username","MSSQL_PASSWORD":"your-password"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "mssql": {
            "command": "python3",
            "args": [
                "/path/to/mcp-sqlserver/src/server.py"
            ],
            "cwd": "/path/to/mcp-sqlserver",
            "env": {
                "MSSQL_SERVER": "your-server",
                "MSSQL_DATABASE": "your-database",
                "MSSQL_USER": "your-username",
                "MSSQL_PASSWORD": "your-password"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "mssql": {
            "command": "python3",
            "args": [
                "/path/to/mcp-sqlserver/src/server.py"
            ],
            "cwd": "/path/to/mcp-sqlserver",
            "env": {
                "MSSQL_SERVER": "your-server",
                "MSSQL_DATABASE": "your-database",
                "MSSQL_USER": "your-username",
                "MSSQL_PASSWORD": "your-password"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect