egarcia74/warp-sql-server-mcp

SQL Server MCP - AI-Powered Database Integration

Connect AI assistants to your SQL Server databases with enterprise-grade security and performance.

🤖 AI-First Database Access: Enable GitHub Copilot, Warp AI, and other assistants to interact with your SQL Server databases through natural language queries, with comprehensive security controls and production-ready reliability.

🚀 Quick Start - Choose Your AI Assistant

New to this project? Get up and running in under 5 minutes!

🤖 GitHub Copilot in VS Code (⭐ Most Popular)

Perfect for developers who want AI-powered SQL assistance directly in their IDE.

• ✅ GitHub Copilot can query your databases directly
• ✅ Context-aware suggestions based on your actual schema
• ✅ Natural language to SQL query generation
• ✅ Real-time insights while coding

💬 Warp Terminal

Ideal for terminal-based workflows and command-line database interactions.

• ✅ AI-powered terminal with SQL Server integration
• ✅ Natural language database queries
• ✅ Fast iteration for analysis and debugging
• ✅ Cross-platform terminal experience

🔧 Advanced Integration

- Advanced workflows and configuration

Using another AI assistant? This MCP server works with any MCP-compatible system.

✨ What You Get

• 🤖 Natural language to SQL - Ask questions, get queries
• 🔒 Enterprise security - Three-tier safety system with secure defaults
• 📊 Performance insights - Query optimization and bottleneck detection
• ☁️ Cloud-ready - AWS/Azure secret management
• 🚀 Streaming support - Memory-efficient handling of large datasets
• 📈 16 Database Tools - Complete database operations through AI

🔒 Security Levels (Quick Reference)

🔒 Maximum Security (Default - Production Recommended):

SQL_SERVER_READ_ONLY=true                      # Only SELECT allowed
SQL_SERVER_ALLOW_DESTRUCTIVE_OPERATIONS=false  # No data modifications
SQL_SERVER_ALLOW_SCHEMA_CHANGES=false         # No schema changes

📋 Essential Environment Variables

📖 Complete Reference: See for comprehensive documentation of all environment variables, defaults, and context-aware behavior.

💡 Authentication: For Windows Authentication, leave SQL_SERVER_USER and SQL_SERVER_PASSWORD empty. 💡 SSL Certificates: SQL_SERVER_TRUST_CERT automatically adapts to your environment (trusts in development, requires valid certificates in production).

🛠️ Installation & Configuration

Note: As of v1.7.11 the package is published under the scoped name @egarcia74/warp-sql-server-mcp. The previous unscoped package remains temporarily and will be deprecated.

⭐ Recommended: Global npm Installation

# Install globally via npm (easiest method)
npm install -g @egarcia74/warp-sql-server-mcp

# Initialize configuration
warp-sql-server-mcp init

# Edit config file with your SQL Server details
# Config file location: ~/.warp-sql-server-mcp.json

Benefits:

• ✅ No manual path configuration
• ✅ Secure credential storage with file permissions (600)
• ✅ Easy configuration updates without touching AI assistant settings
• ✅ Password masking and validation

Alternative: Manual Installation

# Clone and install manually
git clone https://github.com/egarcia74/warp-sql-server-mcp.git
cd warp-sql-server-mcp
npm install

🎯 Use Cases

🔍 Database Analysis & Exploration

• Schema Discovery: Reverse engineer legacy databases without documentation
• Data Quality Assessment: Spot-check data integrity across tables
• New Team Onboarding: Rapidly explore unfamiliar database schemas

📊 Business Intelligence & Reporting

• Ad-hoc Analysis: Quick business questions through natural language
• Data Export: Export filtered datasets to CSV for analysis
• Revenue Analysis: AI-powered business insights

🛠️ Development & DevOps

• Query Performance Tuning: Execution plan analysis and optimization
• API Development: Quickly test database queries during development
• Database Troubleshooting: Debug slow queries and identify bottlenecks

🚀 AI-Powered Operations

• Natural Language to SQL: Ask questions like "Show me customers who haven't placed orders"
• Query Optimization: "Why is this query running slowly?"
• Automated Insights: Generate business reports through conversational queries

📚 Complete Documentation

- Navigate all documentation in one place

User Guides

• - Complete environment variables documentation
• - Comprehensive security configuration and threat model
• - Workflows for reviewing and responding to security alerts
• - Technical deep-dive and system design
• All MCP Tools - Complete API reference (16 tools)

Setup Guides

• - Advanced workflows and configuration
• - Cloud secret management setup
• - Enterprise credential management

Developer Resources

• - Philosophy and engineering practices
• - Real-world analysis of zero-tolerance quality standards
• - Comprehensive test documentation (535+ tests)
• - Development workflow and standards
• - Pre-commit quality gates and guidelines
• - Pre-push validation and deployment guidelines
• - Step-by-step release guide (automation + npm)

🧪 Production Validation

✅ PRODUCTION-VALIDATED: This MCP server has been fully tested through:

• 618+ Comprehensive Tests: All MCP tools, security boundaries, error scenarios (392 unit + 40 manual integration + 20 protocol tests)
• 40 Manual Integration Tests: Live database validation across all security phases
• 20 Protocol Tests: End-to-end MCP communication validation
• 100% Success Rate: All security phases validated in production scenarios

🐳 Quick Testing with Docker (Recommended for Development)

# One-command testing with automated SQL Server container
npm run test:integration

# This will:
# 1. 🐳 Start SQL Server 2022 container
# 2. ⏱️ Wait for database initialization (2-3 minutes)
# 3. 🧪 Run all integration tests
# 4. 🔄 Clean up and stop container

Benefits: ✨ Zero configuration, 🛡️ Complete isolation, ⚡ Fast setup, 📋 Consistent environment

🔧 Manual Setup Testing (Production Validation)

Security Phases Tested:

• Phase 1 (Read-Only): Maximum security - 20/20 tests ✅
• Phase 2 (DML Operations): Selective permissions - 10/10 tests ✅
• Phase 3 (DDL Operations): Full development mode - 10/10 tests ✅

# Quick Start - Get comprehensive help
npm run help               # Show all commands with detailed descriptions

# Run tests locally
npm test                   # All automated unit + integration tests
npm run test:coverage      # Coverage report with detailed metrics
npm run test:integration   # 🚀 Complete integration test suite with Docker
npm run test:integration:ci  # For CI environments with external database
npm run test:integration:performance  # ⭐ Fast performance validation (~2s)

# View logs and monitor activity
npm run logs               # Show recent server logs
npm run logs:tail          # Follow logs in real-time
npm run logs:audit         # Show security audit logs

🔧 Usage Examples

Once configured, you can use natural language with your AI assistant:

VS Code + GitHub Copilot

@sql-server List all databases
@sql-server Show me tables in the AdventureWorks database
@sql-server Generate a query to find the top 10 customers by sales
@sql-server Analyze the performance of this query: SELECT * FROM Orders WHERE OrderDate > '2023-01-01'

Warp Terminal

Please list all databases on the SQL Server
Execute this SQL query: SELECT TOP 10 * FROM Users ORDER BY CreatedDate DESC
Can you describe the structure of the Orders table?
Show me 50 rows from the Products table where Price > 100

🚨 Troubleshooting

Common Issues

Connection Problems:

• Verify SQL Server is running on the specified port: telnet localhost 1433
• Check firewall settings on both client and server
• Enable TCP/IP protocol in SQL Server Configuration Manager

Authentication Issues:

• For SQL Server Auth: Verify SQL_SERVER_USER and SQL_SERVER_PASSWORD
• For Windows Auth: Leave user/password empty, optionally set SQL_SERVER_DOMAIN
• Ensure the connecting user has appropriate database permissions

Configuration Issues:

• Set SQL_SERVER_ENCRYPT=false for local development
• MCP servers require explicit environment variables (.env files are not loaded automatically)
• Check MCP server logs: npm run logs or npm run logs:tail for real-time monitoring
• View audit logs for security-related issues: npm run logs:audit

Platform-Specific

Windows:

• Enable TCP/IP in SQL Server Configuration Manager
• Start SQL Server Browser service for named instances
• Windows Authentication works seamlessly with domain accounts

macOS/Linux:

• Remote SQL Server connections often require SQL Server Authentication
• May need SQL_SERVER_ENCRYPT=true for remote connections
• Test connectivity: nc -zv localhost 1433 or nmap -p 1433 localhost

🤝 Contributing

This project demonstrates enterprise-grade software engineering practices. We welcome contributions that maintain our high standards:

1. Fork the repository and create a feature branch
2. Follow TDD practices - write tests first!
3. Maintain code quality - all commits trigger automated quality checks
4. Add comprehensive tests for new functionality
5. Update documentation as needed
6. Submit a pull request with detailed description

Development Commands:

# Get comprehensive help for all available commands
npm run help               # Show organized command reference with descriptions

# Core development
npm run dev                # Development mode with auto-restart
npm test                   # Run all tests
npm run lint:fix          # Fix linting issues
npm run format            # Format code
npm run ci                 # Full CI pipeline locally

# Log viewing and monitoring
npm run logs               # Show recent server logs
npm run logs:tail          # Follow server logs in real-time
npm run logs:audit         # Show security audit logs
npm run logs:tail:audit    # Follow audit logs in real-time

# System maintenance and cleanup
npm run cleanup            # Clean up leftover test processes
npm run cleanup:processes  # Same as cleanup (alias)

📄 License

This project is licensed under the MIT License - see the file for details.

Copyright (c) 2025 Eduardo Garcia

🌟 About This Project

While this appears to be an MCP server for SQL Server integration, it's fundamentally a comprehensive framework demonstrating enterprise-grade software development practices. Every component, pattern, and principle here showcases rigorous engineering standards that can be applied to any production system.

Key Engineering Highlights:

• 🔬 618+ Comprehensive Tests covering all functionality and edge cases
• 🛡️ Multi-layered Security with defense-in-depth architecture
• 📊 Production Observability with structured logging and performance monitoring
• ⚡ Enterprise Reliability featuring connection pooling and graceful error handling
• 🏛️ Clean Architecture with dependency inversion and modular design
• 📚 Living Documentation that auto-syncs with code changes