mssql-performance-mcp/QUICK_START.md

MCP server for SQL Server performance tuning and optimization. Provides tools for analyzing slow queries, execution plans, index fragmentation, missing indexes, and more.

# Quick Start Guide - MSSQL Performance MCP

Get up and running in 5 minutes!

## ⚡ Installation

```bash
# Install globally with npm
npm install -g mssql-performance-mcp
```

## 🔧 Configure Claude Desktop or Cursor

### Configuration File Locations

**Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Claude Desktop (Windows)**: `%APPDATA%\Claude\claude_desktop_config.json`  
**Cursor**: `~/.cursor/mcp.json`

### Add this configuration:
```json
{
  "mcpServers": {
    "mssql-performance-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mssql-performance-mcp"
      ]
    }
  }
}
```

**That's it!** No need to specify paths - npx will find the globally installed package.

## 🚀 Restart Claude Desktop or Cursor

Close and reopen your application completely.

## ✅ Verify Installation

Look for the 🔌 icon in Claude Desktop. You should see "mssql-performance" listed.

## 🎯 First Query

Try this in Claude:

```
I need to analyze performance on my SQL Server:
Server: localhost
Database: master
User: sa

Can you:
1. Run a health check
2. Show me the top 5 slow queries
3. Check for missing indexes
```

Claude will ask for the password securely.

## 📊 Common First Tasks

### Check Database Health
```
Run a performance health check on server 'my-server' database 'MyDB'
```

### Find Slow Queries
```
Show me the top 10 slowest queries by CPU time on database 'MyDB'
```

### Analyze Indexes
```
Check for missing indexes with high impact on database 'MyDB'
```

### Check Fragmentation
```
Show index fragmentation for database 'MyDB' where fragmentation > 20%
```

## 🔐 SQL Server Permissions

Your SQL Server user needs these permissions:

```sql
-- Grant required permissions
GRANT VIEW SERVER STATE TO [your_user];
GRANT VIEW DATABASE STATE TO [your_user];
GRANT VIEW DEFINITION TO [your_user];

-- Or add to sysadmin (not recommended for production)
ALTER SERVER ROLE sysadmin ADD MEMBER [your_user];
```

## 🛠️ Troubleshooting

### "Cannot find module" error
```bash
# Reinstall the package globally
npm install -g mssql-performance-mcp
```

### "Connection failed" error
- Check SQL Server is running
- Verify firewall allows connections
- Confirm SQL Server authentication is enabled
- Test connection with: `sqlcmd -S server -U user -P password`

### "Permission denied" on DMVs
```sql
-- Run on SQL Server as admin
GRANT VIEW SERVER STATE TO [your_user];
```

### MCP server not showing in Claude or Cursor
1. Verify global installation: `npm list -g mssql-performance-mcp`
2. Check the config file syntax (valid JSON)
3. Restart your application completely (Claude Desktop or Cursor)
4. Check application logs for errors

## 📖 Next Steps

1. Read [README.md](./README.md) for detailed tool documentation
2. Check [USAGE_EXAMPLES.md](./USAGE_EXAMPLES.md) for real-world scenarios
3. Start with `get_performance_health_check` to understand your database

## 💡 Tips

- **Always use production credentials carefully** - consider using a read-only monitoring account
- **Start with health checks** before diving into specific issues
- **Test recommendations in non-production** environments first
- **Use Query Store** for historical analysis (enable it if not already)

## 🎓 Learning Resources

### Essential Queries to Know
1. `get_performance_health_check` - Your starting point
2. `get_slow_queries` - Find performance issues
3. `get_wait_statistics` - Understand bottlenecks
4. `get_missing_indexes` - Quick wins
5. `generate_index_maintenance_script` - Automated maintenance

### Understanding Results

**High CPU queries** → Consider indexes, query optimization
**PAGEIOLATCH waits** → I/O bottleneck, need more memory or faster disks
**WRITELOG waits** → Transaction log disk slow
**LCK_M waits** → Blocking/locking issues

## 🔄 Updates

To update to the latest version:

```bash
npm update -g mssql-performance-mcp
# Then restart Claude Desktop or Cursor
```

## 📞 Getting Help

1. Check the [README.md](./README.md) documentation
2. Review [USAGE_EXAMPLES.md](./USAGE_EXAMPLES.md) for similar scenarios
3. Ask Claude: "How do I use the mssql-performance MCP server?"

---

**You're all set!** 🎉 Start asking Claude about your SQL Server performance!