Warp SQL Server MCP

Enterprise-Grade Software Framework

A Comprehensive Reference Implementation for Production-Ready Systems

What you're looking at: While this appears to be an MCP server for SQL Server integration, it's fundamentally a complete framework demonstrating enterprise-grade software development practices. Every component, pattern, and principle here is designed to showcase rigorous engineering standards that can be applied to any production system.

🏗️ Framework Highlights

🔬 Comprehensive Testing Strategy: 535 tests covering unit, integration, and edge cases with 95%+ coverage 🛡️ Multi-layered Security Architecture: Defense-in-depth security with audit logging and threat detection
📊 Production Observability: Performance monitoring, structured logging, and health assessment
⚡ Enterprise Reliability: Connection pooling, circuit breakers, and graceful error handling
🏛️ Clean Architecture: Layered design with dependency inversion and interface segregation
📚 Living Documentation: Auto-generated docs that stay synchronized with code changes

Build & Quality Status

Automation & Monitoring

Project Info

🎯 The Real Value Proposition

This codebase demonstrates how to build enterprise-grade software that actually works in production. While it delivers MCP functionality for SQL Server integration, its primary value lies in the comprehensive engineering practices it showcases:

Production-Ready Patterns

• Observability: Structured logging, performance monitoring, health checks
• Reliability: Connection pooling, retry logic, circuit breakers, graceful degradation
• Security: Multi-layer validation, audit logging, threat detection, secure defaults
• Testability: Comprehensive test coverage with proper mocking strategies
• Maintainability: Clean architecture, dependency injection, configuration management

Enterprise Architecture

• Layered Design: Clear separation between presentation, business logic, and data layers
• Interface Segregation: Components depend only on what they actually use
• Dependency Inversion: High-level modules don't depend on low-level implementation details
• Single Responsibility: Each component has one well-defined purpose
• Open/Closed Principle: Easy to extend without modifying existing code

See our Software Engineering Manifesto and Architecture Guide for the complete philosophy and technical details.

🚀 Quick Start

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

Choose Your Development Environment

🖥️ Warp Terminal Quick Start → - Original 5-minute setup for Warp Terminal

💻 VS Code Quick Start → - Complete VS Code + Warp integration setup

Advanced Setup Guides

🔧 Complete VS Code Integration Guide → - Comprehensive development workflow

For detailed configuration options, continue reading below.

Features

• Database Connection: Connect to SQL Server on localhost:1433 (configurable)
• Query Execution: Execute arbitrary SQL queries with graduated safety controls
• Schema Inspection: List databases, tables, and describe table structures
• Data Retrieval: Get sample data from tables with filtering and limiting
• Authentication: Support for both SQL Server authentication and Windows authentication
• 🔒 Security: Three-tier graduated safety system with secure defaults
• ☁️ Cloud-Ready: Enterprise secret management with AWS Secrets Manager and Azure Key Vault
• 🚀 Streaming: Memory-efficient handling of large datasets
• 📊 Performance Monitoring: Real-time query performance tracking and optimization

🔒 Security

✨ NEW: This MCP now includes a revolutionary three-tier graduated safety system designed to prevent accidental or malicious database operations while providing the flexibility needed for different environments.

🛡️ Three-Tier Safety System

The MCP server implements three independent security layers that can be configured separately:

🏗️ Security Configurations

🔒 Maximum Security (Default - Production Recommended)

✅ Allowed Operations:

• SELECT queries (JOINs, CTEs, subqueries)
• Database and table inspection
• Query performance analysis
• Data export (CSV)

❌ Blocked Operations:

• INSERT, UPDATE, DELETE, TRUNCATE
• CREATE, DROP, ALTER operations
• Stored procedure execution

🎯 Perfect For: Production monitoring, business intelligence, reporting, data analysis

📊 Data Analysis Mode

✅ Additional Operations Allowed:

• INSERT, UPDATE, DELETE operations
• Data import/migration
• ETL processes

❌ Still Blocked:

• CREATE, DROP, ALTER operations
• Schema modifications

🎯 Perfect For: Development environments, data migration, ETL processes, application testing

🛠️ Full Development Mode (Use with Caution)

✅ All Operations Allowed:

• Complete SQL functionality
• Database schema modifications
• Index and constraint management

⚠️ WARNING: This provides unrestricted database access. Only use in isolated development environments!

🎯 Perfect For: Database development, schema migration, isolated development environments

🚨 Security Status Monitoring

Startup Security Summary

The MCP server displays security status on startup in the Warp logs:

Runtime Security Information

Every query response includes current security status:

🔍 Query Validation

The MCP server includes intelligent query validation that:

1. Analyzes SQL patterns before execution
2. Blocks dangerous operations based on current security settings
3. Provides clear error messages explaining why operations were blocked
4. Suggests configuration changes when operations are blocked

Example Security Block:

🏥 Production Deployment

Recommended Production Configuration

Security Validation Checklist

Before deploying to production:

• ✅ Read-only mode enabled (SQL_SERVER_READ_ONLY=true)
• ✅ Destructive operations blocked (SQL_SERVER_ALLOW_DESTRUCTIVE_OPERATIONS=false)
• ✅ Schema changes blocked (SQL_SERVER_ALLOW_SCHEMA_CHANGES=false)
• ✅ Encryption enabled (SQL_SERVER_ENCRYPT=true)
• ✅ Certificate validation enabled (SQL_SERVER_TRUST_CERT=false)
• ✅ Security warnings appear in logs during startup
• ✅ Test blocked operations return appropriate error messages
• ✅ Document security settings in deployment documentation

🔧 Migration from Previous Versions

⚠️ Breaking Change Notice: Starting with this version, the MCP server defaults to maximum security (read-only mode).

If you need write access, explicitly configure:

📚 Additional Security Resources

• Complete Security Documentation - Comprehensive security guide
• Threat Model Analysis - What threats are mitigated
• Security Testing Guide - How to validate security features
• Deployment Guidelines - Environment-specific recommendations
• Azure Key Vault Configuration Guide - Complete setup guide for Azure Key Vault secret management
• AWS Secrets Manager Configuration Guide - Complete setup guide for AWS Secrets Manager with IAM roles and JSON secrets

🎯 Use Cases

This MCP transforms Warp into a lightweight, AI-powered database client perfect for developers, analysts, DBAs, and business users. Here are the most valuable use cases:

🔍 Database Analysis & Exploration

Schema Discovery

• Reverse engineer legacy databases without documentation
• Quick database audits to understand structure and relationships
• New team onboarding - rapidly explore unfamiliar database schemas
• Data migration planning - understand source system structure

Data Quality Assessment

• Spot-check data integrity across tables
• Identify orphaned records or referential integrity issues
• Sample data for quality analysis before major operations

📊 Business Intelligence & Reporting

Ad-hoc Analysis

• Quick business questions: "How many orders are pending?"
• Revenue analysis: "What are our top-selling products?"
• Customer insights: "Which customers haven't placed orders recently?"
• Inventory monitoring: "What products are low in stock?"

Data Export for Analysis

• Export filtered datasets to CSV for Excel/BI tool analysis
• Extract sample data for testing or development environments
• Generate reports for stakeholders who prefer spreadsheet format

🛠️ Development & DevOps

Database Troubleshooting

• Query performance tuning using execution plan analysis
• Debug slow queries by examining actual vs estimated plans
• Identify missing indexes or inefficient query patterns
• Monitor query execution costs

Development Support

• API development - quickly test database queries during development
• Data seeding - understand existing data patterns for test data creation
• Schema validation - verify database changes deployed correctly
• Integration testing - validate data flows between systems

🔧 Database Administration

Maintenance & Monitoring

• Quick health checks across multiple databases
• Verify foreign key constraints are properly implemented
• Monitor table sizes and row counts
• Validate data consistency after migrations

Documentation & Compliance

• Generate schema documentation automatically
• Create data dictionaries for compliance audits
• Document foreign key relationships for impact analysis
• Export metadata for governance tools

🎓 Education & Training

SQL Learning

• Safe environment to explore database concepts
• Learn complex JOIN patterns on real data
• Practice query optimization techniques
• Understand execution plans and performance tuning

Database Design Training

• Analyze well-designed schemas from existing databases
• Study foreign key implementation patterns
• Learn normalization principles from real examples

🚀 AI-Powered Database Operations

Natural Language to SQL

With Warp's AI capabilities, you can:

• Ask: "Show me customers who haven't placed orders"
• Query: "What's our revenue by product category?"
• Analyze: "Which products are selling best this month?"
• Optimize: "Why is this query running slowly?"

Automated Insights

• Generate business reports through conversational queries
• Perform data analysis without writing complex SQL
• Get explanations of query performance issues in plain English

🏢 Enterprise Scenarios

Multi-Database Management

• Compare schemas across development/staging/production
• Validate data consistency across environments
• Monitor multiple SQL Server instances from one interface
• Coordinate database operations across teams

Legacy System Integration

• Understand undocumented legacy database structures
• Extract data from legacy systems for modernization projects
• Bridge between old systems and modern applications
• Support gradual migration strategies

💡 Why This MCP is Particularly Powerful

1. Zero Configuration - No need to install heavy database tools
2. AI Integration - Natural language queries through Warp
3. Flexible Access - Full SQL capabilities from simple queries to complex operations
4. Fast Iteration - Quick feedback loop for analysis and development
5. Cross-Platform - Works on any system where Warp runs
6. Comprehensive - All essential database operations in one tool

Available Tools

Database Operations

1. execute_query: Execute any SQL query on the connected database
2. list_databases: List all user databases on the SQL Server instance
3. list_tables: List all tables in a specific database/schema
4. describe_table: Get detailed schema information for a table
5. get_table_data: Retrieve sample data from tables with optional filtering
6. explain_query: Analyze query performance with execution plans and cost information
7. list_foreign_keys: Discover foreign key relationships and constraints in a schema
8. export_table_csv: Export table data in CSV format with optional filtering

Performance Monitoring

1. get_performance_stats: Get comprehensive server performance statistics and health metrics
2. get_query_performance: Get detailed query performance breakdown by tool with filtering options
3. get_connection_health: Monitor SQL Server connection pool health and diagnostics

Query Optimization (NEW)

1. get_index_recommendations: Analyze database usage patterns and recommend missing indexes
2. analyze_query_performance: Deep analysis of specific queries with optimization suggestions
3. detect_query_bottlenecks: Identify and categorize performance bottlenecks across queries
4. get_optimization_insights: Comprehensive database health analysis and optimization roadmap

Installation

⭐ Recommended: Global npm Installation

Advantages:

• ✅ No manual path configuration
• ✅ Automatic dependency management
• ✅ Easy configuration with secure credential storage
• ✅ Simple Warp integration
• ✅ Updates available via npm update -g

Alternative: Manual Installation

Prerequisites

• Node.js 18.0.0 or higher (works on Windows, macOS, and Linux)
• SQL Server instance running on localhost:1433 (or configured host/port)
• Appropriate database permissions for the connecting user

Platform-Specific Setup

🪟 Windows Setup

Advantages on Windows:

• Native SQL Server integration
• Superior Windows Authentication support
• Seamless domain integration
• Fewer cross-platform authentication issues

Prerequisites:

1. Node.js 18+: Download from nodejs.org
2. SQL Server: SQL Server Express (free) or full SQL Server
3. SQL Server Configuration:
   • Enable TCP/IP protocol in SQL Server Configuration Manager
   • Start SQL Server Browser service (for named instances)
   • Configure Windows Firewall if needed

Installation:

Configuration (.env file):

🍎🐧 macOS/Linux Setup

Installation:

Configuration (.env file):

Common Configuration

Configuration for Warp and MCP Clients

Method 1: CLI Configuration (⭐ Recommended)

This is the easiest way to configure the MCP server with secure credential storage:

1. Install globally and initialize:
   npm install -g @egarcia74/warp-sql-server-mcp warp-sql-server-mcp init
2. Edit configuration file (opens at ~/.warp-sql-server-mcp.json):
   { "SQL_SERVER_HOST": "localhost", "SQL_SERVER_PORT": "1433", "SQL_SERVER_DATABASE": "master", "SQL_SERVER_USER": "your_username", "SQL_SERVER_PASSWORD": "your_password", "SQL_SERVER_ENCRYPT": "false", "SQL_SERVER_TRUST_CERT": "true", "SQL_SERVER_READ_ONLY": "true", "SQL_SERVER_ALLOW_DESTRUCTIVE_OPERATIONS": "false", "SQL_SERVER_ALLOW_SCHEMA_CHANGES": "false" }
3. Configure Warp MCP Settings:
   • Open Warp Settings: Cmd+, → MCP tab
   • Click "Add MCP Server"
   • Name: sql-server
   • Command: warp-sql-server-mcp
   • Args: ["start"]
   • No environment variables needed! ✨

Benefits:

• ✅ Secure credential storage with restrictive file permissions (600)
• ✅ No complex Warp environment variable configuration
• ✅ Easy to update configuration without touching Warp settings
• ✅ Configuration validation and helpful error messages
• ✅ Masked passwords when viewing config with warp-sql-server-mcp config

Method 2: Manual Warp Configuration (Advanced)

⚠️ NOTE: MCP servers run in isolated environments and do not automatically load .env files. You must explicitly provide all configuration through environment variables.

1. Open Warp Settings:
   • Press Cmd+, or go to Warp → Settings
   • Navigate to the MCP section
2. Add New MCP Server:
   • Click "Add MCP Server"
   • Name: sql-server
   • Command: node
   • Args (choose based on your installation):
     • Global npm install: ["warp-sql-server-mcp", "start"]
     • Manual install: ["/full/path/to/warp-sql-server-mcp/index.js"]
3. Environment Variables (required for manual configuration):
   { "SQL_SERVER_HOST": "localhost", "SQL_SERVER_PORT": "1433", "SQL_SERVER_DATABASE": "master", "SQL_SERVER_USER": "your_username", "SQL_SERVER_PASSWORD": "your_password", "SQL_SERVER_ENCRYPT": "false", "SQL_SERVER_TRUST_CERT": "true", "SQL_SERVER_READ_ONLY": "true", "SQL_SERVER_ALLOW_DESTRUCTIVE_OPERATIONS": "false", "SQL_SERVER_ALLOW_SCHEMA_CHANGES": "false" }
4. Authentication Options:
   • For SQL Server Authentication: Include SQL_SERVER_USER and SQL_SERVER_PASSWORD
   • For Windows Authentication: Omit SQL_SERVER_USER and SQL_SERVER_PASSWORD, optionally add SQL_SERVER_DOMAIN
5. Save Configuration and restart the MCP server

Method 2: JSON Configuration File

Create or update your MCP configuration file (e.g., warp-mcp-config.json):

Import into Warp:

1. Save the JSON configuration file
2. In Warp Settings → MCP, click "Import Configuration"
3. Select your JSON file

Configuration for Other MCP Clients

For other MCP-compatible systems (Claude Desktop, etc.), use a similar JSON structure:

Environment Variables Reference

Core Connection Settings

🔒 Security Configuration (NEW)

⚠️ Important: These settings significantly impact security. See Security section for detailed guidance.

Troubleshooting Configuration

Common Issues:

1. "NTLM authentication error"
   • Ensure SQL_SERVER_USER and SQL_SERVER_PASSWORD are set for SQL Server auth
   • Or omit both for Windows authentication
2. "Connection timeout"
   • Set SQL_SERVER_ENCRYPT=false for local development
   • Verify SQL Server is running on the specified port
   • Check firewall settings
3. "Server not found"
   • Verify SQL_SERVER_HOST and SQL_SERVER_PORT are correct
   • Test connectivity: telnet localhost 1433
4. "Login failed"
   • Verify username/password in SQL_SERVER_USER and SQL_SERVER_PASSWORD
   • Ensure the user has database access permissions

Verification Steps:

1. Check MCP server logs in Warp for startup messages
2. Look for: "Database connection pool initialized successfully"
3. Test with simple query: "List all databases"
4. Check Warp's MCP server status in Settings

Usage Examples

Once configured, you can use the MCP tools in Warp:

List all databases

Execute a query

Describe a table structure

Get sample data with filtering

Security Considerations

• Environment Variables: Store sensitive connection details in environment variables, not in code
• Least Privilege: Use database accounts with minimal required permissions
• Network Security: Ensure your SQL Server is properly configured for your network environment
• SSL/TLS: Consider enabling encryption for production environments

Authentication Methods

SQL Server Authentication

Set these environment variables:

Windows Authentication

Leave SQL_SERVER_USER and SQL_SERVER_PASSWORD empty. Optionally set:

Error Handling

The MCP server includes comprehensive error handling for:

• Connection failures
• Authentication issues
• SQL syntax errors
• Permission denied errors
• Network timeouts

All errors are returned as structured MCP error responses with descriptive messages.

Development

To run in development mode with auto-restart:

To test the server standalone:

Testing

This project includes comprehensive unit tests for all functionality using Vitest.

📖 For detailed test documentation, see test/README.md

Quick Start

Test Overview

• Total Tests: 535 tests covering all MCP tools and functionality
• Test Framework: Vitest with comprehensive mocking
• Coverage: 60.25% statements, 78.04% branches, 83.33% functions
• Architecture: Unit tests with mocked SQL Server connections for reliability and speed

Test Categories

The test suite covers:

• Core functionality: All 15 MCP tools (execute_query, list_databases, optimization tools, etc.)
• Connection handling: Database connection logic and authentication methods
• Error scenarios: Comprehensive error handling and edge cases
• Advanced features: Query analysis, foreign keys, CSV export with filtering
• WHERE clause filtering: 16 comprehensive filtering tests preventing parameter bugs

Test Documentation

For complete test documentation including:

• Detailed test breakdowns by category
• Test architecture and mocking strategy
• Development workflow and best practices
• Coverage analysis and debugging guides

👉 See test/README.md

Documentation

This project features an enhanced auto-generated documentation system that ensures documentation never goes out of sync with the actual code.

📖 Online Documentation

• Main Documentation Site - Overview, setup guides, and quick reference
• Complete API Reference - Detailed documentation for all 15 MCP tools with parameters and examples
• Test Coverage Reports - Live test coverage analysis

🔄 Auto-Generated Documentation

Our documentation system automatically:

• Extracts tool definitions directly from the source code (index.js)
• Generates parameter tables with types, descriptions, and requirements
• Creates usage examples for basic and advanced scenarios
• Updates version numbers and tool counts dynamically
• Maintains consistency between code and documentation

📝 Documentation Scripts

The documentation generation happens through three specialized scripts:

🚀 Automatic Updates

The documentation automatically rebuilds on every push to the main branch via GitHub Actions, ensuring:

• Always current: Documentation reflects the latest code changes
• No manual maintenance: Tool lists and parameters update automatically
• Professional presentation: Clean, navigable documentation site
• Comprehensive coverage: Full API reference with examples

🛠️ For Contributors

When adding new MCP tools or modifying existing ones:

1. Update the code in index.js with proper tool definitions
2. Documentation updates automatically - no manual changes needed!
3. Verify locally by running the documentation scripts
4. Push changes - GitHub Actions handles the rest

The system parses your MCP tool definitions and extracts:

• Tool names and descriptions
• Parameter schemas with types
• Required vs optional parameters
• Auto-generated usage examples

Troubleshooting

🪟 Windows-Specific Troubleshooting

SQL Server Configuration:

1. Enable TCP/IP Protocol:
   • Open "SQL Server Configuration Manager"
   • Navigate to "SQL Server Network Configuration" → "Protocols for [Instance]"
   • Enable "TCP/IP" protocol
   • Restart SQL Server service
2. SQL Server Browser Service:
   • Open "Services" (services.msc)
   • Start "SQL Server Browser" service
   • Set to "Automatic" startup type
3. Windows Firewall:
   • Add inbound rule for port 1433
   • Or temporarily disable firewall for testing
4. Windows Authentication:
   • Works seamlessly with domain accounts
   • Run Warp as the user who needs database access
   • No username/password required in configuration

Testing Connection:

🍎🐧 macOS/Linux-Specific Troubleshooting

Connection Testing:

Common Issues:

1. Remote SQL Server: Often requires SQL Server Authentication
2. SSL/TLS: May need SQL_SERVER_ENCRYPT=true for remote connections
3. Network: Check firewall rules on SQL Server host
4. Docker: If using SQL Server in Docker, ensure port mapping

General Connection Issues

• Verify SQL Server is running and accepting connections on port 1433
• Check firewall settings on both client and server
• Ensure TCP/IP protocol is enabled in SQL Server Configuration Manager
• Verify authentication credentials are correct

Permission Issues

• Ensure the connecting user has appropriate database permissions
• For Windows Authentication: Run the process with appropriate user context
• For SQL Server Authentication: Verify the SQL login exists and has permissions

Network Issues

• Test connectivity using tools like telnet localhost 1433
• Check SQL Server network configuration
• Verify named pipes vs TCP/IP settings
• Check for VPN or proxy interference

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

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

Copyright (c) 2025 Eduardo Garcia-Prieto