sqlserver-mcp-colossal/docs/QUICKSTART.md

MCP Server for SQL Server database operations with comprehensive CRUD functionality, views, stored procedures, execution plan analysis, and safety features

# SQL Server MCP Colossal - Quick Start Guide

## Overview

This guide will help you quickly set up and use the SQL Server MCP Colossal with Claude Desktop.

## Prerequisites

- Python 3.10+
- SQL Server with ODBC Driver 17
- Claude Desktop
- Network access to your SQL Server

## Quick Setup

### 1. Install Dependencies

```bash
# Clone or download the project
cd SQLSERVER-MCP-COLOSSAL

# Install Python dependencies
pip install -r requirements.txt
```

### 2. Configure SQL Server Connection

**Option A: Environment Variables (Recommended)**
```bash
# Copy the template
cp config/env.template config/.env

# Edit with your SQL Server details
# SQLSERVER_HOST=your-server
# SQLSERVER_DATABASE=your-database
# SQLSERVER_USERNAME=your-username
# SQLSERVER_PASSWORD=your-password
```

**Option B: Configuration File**
```bash
# Copy the template
cp config/sqlserver_config.json.template config/sqlserver_config.json

# Edit with your SQL Server details
```

### 3. Configure Claude Desktop

Add to your Claude Desktop config file:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "sqlserver-colossal": {
      "command": "python",
      "args": ["C:\\path\\to\\SQLSERVER-MCP-COLOSSAL\\src\\server.py"],
      "env": {
        "SQLSERVER_HOST": "your-server",
        "SQLSERVER_DATABASE": "your-database", 
        "SQLSERVER_USERNAME": "your-username",
        "SQLSERVER_PASSWORD": "your-password"
      }
    }
  }
}
```

### 4. Restart Claude Desktop

Completely quit and restart Claude Desktop to load the new configuration.

## Testing the Connection

In Claude Desktop, try these commands:

1. **Configure Connection:**
   ```
   Configure SQL Server connection:
   - Server: localhost
   - Database: AdventureWorks
   - Username: sa
   - Password: YourPassword123
   ```

2. **Test Connection:**
   ```
   List all tables in the database
   ```

3. **Query Data:**
   ```
   Show me the first 10 rows from the Products table
   ```

## Common Commands

### Database Exploration
- "List all tables in the database"
- "Describe the structure of the 'Products' table"
- "Show me the first 20 rows from the 'Customers' table"

### Data Operations
- "Insert a new product: Name='New Product', Price=29.99, Category='Electronics'"
- "Update the price of product ID 1 to 39.99" (requires confirmation)
- "Delete all products with category 'Discontinued'" (requires confirmation)

### Safety Features
- **UPDATE operations require confirmation**: Add `confirm=True` to proceed
- **DELETE operations require confirmation**: Add `confirm=True` to proceed
- **Always review WHERE clauses** before confirming destructive operations

### Custom Queries
- "Execute this query: SELECT COUNT(*) FROM Products WHERE Price > 50"
- "Show me all customers from California"
- "Find products with low stock (quantity < 10)"

## Troubleshooting

### Connection Issues
1. **"SQL Server not configured"**
   - Run the configure_sqlserver tool first
   - Check your configuration file or environment variables

2. **"Connection failed"**
   - Verify server hostname/IP and port
   - Check username and password
   - Ensure SQL Server is running and accessible
   - Verify ODBC Driver 17 is installed

3. **"Permission denied"**
   - Check user has appropriate database permissions
   - Verify SQL Server authentication mode
   - Ensure user can connect to the specified database

4. **"Confirmation required"**
   - Add `confirm=True` for UPDATE/DELETE operations
   - Review WHERE clause before confirming
   - Test queries on non-production data first

### Performance Tips
- Use LIMIT/TOP clauses for large result sets
- Index frequently queried columns
- Use parameterized queries for better performance
- Consider connection pooling for high-volume operations

## Security Best Practices

1. **Credentials Management**
   - Use environment variables for sensitive data
   - Never commit passwords to version control
   - Rotate passwords regularly

2. **Network Security**
   - Use encrypted connections (encrypt=true)
   - Configure proper firewall rules
   - Use VPN for remote connections

3. **Database Security**
   - Follow principle of least privilege
   - Use dedicated service accounts
   - Enable SQL Server audit logging

## Advanced Configuration

### Multiple Environments
```bash
# Development
SQLSERVER_HOST=dev-sqlserver.company.com
SQLSERVER_DATABASE=DevDB

# Production  
SQLSERVER_HOST=prod-sqlserver.company.com
SQLSERVER_DATABASE=ProdDB
```

### Custom ODBC Drivers
```json
{
  "driver": "{ODBC Driver 18 for SQL Server}",
  "trust_server_certificate": false,
  "encrypt": true
}
```

### Connection Pooling
The server automatically manages connections and uses async operations for better performance.

## Support

- **Documentation:** [Full README](README.md)
- **Issues:** Create a GitHub issue
- **Email:** support@javiandev.com
- **MCP Docs:** [Model Context Protocol](https://modelcontextprotocol.io/docs/)

## Next Steps

1. Explore your database structure
2. Set up automated queries
3. Create custom reporting workflows
4. Integrate with other MCP servers
5. Build advanced data analysis pipelines