MCPQL - SQL Server MCP

A comprehensive Model Context Protocol (MCP) server for SQL Server database operations. This server provides 10 powerful tools for database analysis, object discovery, and data manipulation through the MCP protocol.

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• SQL Server database with appropriate connection credentials
• MCP-compatible client (like Claude Desktop, Cursor IDE, or any MCP client)

Installation & Configuration

Option 1: Using npx from GitHub (Recommended)

No installation needed! Just configure your MCP client:

For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "sql",
        "DB_SERVER": "your_server",
        "DB_NAME": "your_database",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_PORT": "1433",
        "DB_ENCRYPT": "false",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

For Cursor IDE:

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "sql",
        "DB_SERVER": "your_server",
        "DB_NAME": "your_database",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_PORT": "1433",
        "DB_ENCRYPT": "false",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

Option 2: Local Development Installation

1. Clone and setup:

git clone https://github.com/hendrickcastro/MCPQL.git
cd MCPQL
npm install
npm run build

2. Configure database connection: Create a .env file with your database credentials:

# Basic SQL Server connection
DB_AUTHENTICATION_TYPE=sql
DB_SERVER=localhost
DB_NAME=MyDatabase
DB_USER=sa
DB_PASSWORD=YourPassword123!
DB_PORT=1433
DB_ENCRYPT=false
DB_TRUST_SERVER_CERTIFICATE=true

3. Configure MCP client with local path:

{
  "mcpServers": {
    "mcpql": {
      "command": "node",
      "args": ["path/to/MCPQL/dist/server.js"]
    }
  }
}

🛠️ Available Tools

MCPQL provides 11 comprehensive tools for SQL Server database operations:

1. 🏗️ Table Analysis - mcp_table_analysis

Complete table structure analysis including columns, keys, indexes, and constraints.

2. 📋 Stored Procedure Analysis - mcp_sp_structure

Analyze stored procedure structure including parameters, dependencies, and source code.

3. 👀 Data Preview - mcp_preview_data

Preview table data with optional filtering and row limits.

4. 📊 Column Statistics - mcp_get_column_stats

Get comprehensive statistics for a specific column.

5. ⚙️ Execute Stored Procedure - mcp_execute_procedure

Execute stored procedures with parameters and return results.

6. 🔍 Execute SQL Query - mcp_execute_query

Execute custom SQL queries with full error handling.

7. ⚡ Quick Data Analysis - mcp_quick_data_analysis

Quick statistical analysis including row count, column distributions, and top values.

8. 🔎 Comprehensive Search - mcp_search_comprehensive

Search across database objects by name and definition with configurable criteria.

9. 🔗 Object Dependencies - mcp_get_dependencies

Get dependencies for database objects (tables, views, stored procedures, etc.).

10. 🎯 Sample Values - mcp_get_sample_values

Get sample values from a specific column in a table.

11. 🔒 Security Status - mcp_get_security_status

Get current security configuration and status for database operations.

📋 Usage Examples

Analyzing a Table

// Get complete table structure
const analysis = await mcp_table_analysis({ 
  table_name: "dbo.Users" 
});

// Get quick data overview
const overview = await mcp_quick_data_analysis({ 
  table_name: "dbo.Users",
  sample_size: 500
});

// Preview table data with filters
const data = await mcp_preview_data({
  table_name: "dbo.Users",
  filters: { "Status": "Active", "Department": "IT" },
  limit: 25
});

Finding Database Objects

// Find all objects containing "User"
const objects = await mcp_search_comprehensive({ 
  pattern: "User",
  search_in_names: true,
  search_in_definitions: false
});

// Find procedures that query a specific table
const procedures = await mcp_search_comprehensive({ 
  pattern: "FROM Users",
  object_types: ["PROCEDURE"],
  search_in_definitions: true
});

Analyzing Stored Procedures

// Get complete stored procedure analysis
const spAnalysis = await mcp_sp_structure({ 
  sp_name: "dbo.usp_GetUserData" 
});

// Execute a stored procedure
const result = await mcp_execute_procedure({
  sp_name: "dbo.usp_GetUserById",
  params: { "UserId": 123, "IncludeDetails": true }
});

Data Analysis

// Get column statistics
const stats = await mcp_get_column_stats({
  table_name: "dbo.Users",
  column_name: "Age"
});

// Get sample values from a column
const samples = await mcp_get_sample_values({
  table_name: "dbo.Users",
  column_name: "Department",
  limit: 15
});

🔧 Environment Variables & Connection Types

MCPQL supports multiple SQL Server connection types with comprehensive configuration options:

🔐 Authentication Types

Set DB_AUTHENTICATION_TYPE to one of:

• sql - SQL Server Authentication (default)
• windows - Windows Authentication
• azure-ad - Azure Active Directory Authentication

📋 Complete Environment Variables

| Variable | Description | Default | Required For | |----------|-------------|---------|--------------| | Basic Connection | | DB_AUTHENTICATION_TYPE | Authentication type (sql/windows/azure-ad) | sql | All | | DB_SERVER | SQL Server hostname/IP | - | All | | DB_NAME | Database name | - | All | | DB_PORT | SQL Server port | 1433 | All | | DB_TIMEOUT | Connection timeout (ms) | 30000 | All | | DB_REQUEST_TIMEOUT | Request timeout (ms) | 30000 | All | | SQL Server Authentication | | DB_USER | SQL Server username | - | SQL Auth | | DB_PASSWORD | SQL Server password | - | SQL Auth | | Windows Authentication | | DB_DOMAIN | Windows domain | - | Windows Auth | | DB_USER | Windows username | current user | Windows Auth | | DB_PASSWORD | Windows password | - | Windows Auth | | Azure AD Authentication | | DB_USER | Azure AD username | - | Azure AD (Password) | | DB_PASSWORD | Azure AD password | - | Azure AD (Password) | | DB_AZURE_CLIENT_ID | Azure AD App Client ID | - | Azure AD (Service Principal) | | DB_AZURE_CLIENT_SECRET | Azure AD App Client Secret | - | Azure AD (Service Principal) | | DB_AZURE_TENANT_ID | Azure AD Tenant ID | - | Azure AD (Service Principal) | | SQL Server Express | | DB_INSTANCE_NAME | Named instance (e.g., SQLEXPRESS) | - | Express instances | | Security Settings | | DB_ENCRYPT | Enable encryption | false | All | | DB_TRUST_SERVER_CERTIFICATE | Trust server certificate | false | All | | DB_ENABLE_ARITH_ABORT | Enable arithmetic abort | true | All | | DB_USE_UTC | Use UTC for dates | true | All | | Connection Pool | | DB_POOL_MAX | Maximum connections | 10 | All | | DB_POOL_MIN | Minimum connections | 0 | All | | DB_POOL_IDLE_TIMEOUT | Idle timeout (ms) | 30000 | All | | Advanced Settings | | DB_CANCEL_TIMEOUT | Cancel timeout (ms) | 5000 | All | | DB_PACKET_SIZE | Packet size (bytes) | 4096 | All | | DB_CONNECTION_STRING | Complete connection string | - | Alternative to individual settings | | Security Controls | | DB_ALLOW_MODIFICATIONS | Allow DML/DDL operations | false | All | | DB_ALLOW_STORED_PROCEDURES | Allow stored procedure execution | false | Al