INSTALL.md•6.57 kB
# Installation Guide
This guide helps you install and configure the MCP SQL Server for use with Claude Desktop, Claude Code CLI, and other MCP-compatible applications.
## Prerequisites
- **Node.js 18+** - [Download here](https://nodejs.org/)
- **SQL Server access** with read permissions
- **Claude Desktop** or other MCP-compatible client
## Step-by-Step Installation
### 1. Install the Package
Choose one of these methods:
#### Global Installation (Recommended for most users)
```bash
npm install -g @bilims/mcp-sqlserver
```
✅ **Pros**: Available system-wide, easy to use
❌ **Cons**: Requires admin permissions on some systems
#### Local Installation
```bash
npm install @bilims/mcp-sqlserver
```
✅ **Pros**: No admin permissions needed
❌ **Cons**: Must use `npx` to run
#### Direct Run (No Installation)
```bash
npx @bilims/mcp-sqlserver
```
✅ **Pros**: No installation required
❌ **Cons**: Downloads package each time
### 2. Verify Installation
```bash
# For global installation
mcp-sqlserver --help
# For local installation
npx mcp-sqlserver --help
# You should see usage information if installed correctly
```
### 3. Configure Environment Variables
Create a `.env` file or set environment variables:
#### Option A: Environment Variables
```bash
export SQLSERVER_HOST="your-server.database.windows.net"
export SQLSERVER_USER="your-username"
export SQLSERVER_PASSWORD="your-password"
export SQLSERVER_DATABASE="your-database"
export SQLSERVER_ENCRYPT="true"
export SQLSERVER_TRUST_CERT="false" # Use "true" for self-signed certificates
```
#### Option B: .env File
Create a `.env` file in your project directory:
```env
SQLSERVER_HOST=your-server.database.windows.net
SQLSERVER_USER=your-username
SQLSERVER_PASSWORD=your-password
SQLSERVER_DATABASE=your-database
SQLSERVER_ENCRYPT=true
SQLSERVER_TRUST_CERT=false
```
### 4. Test the Connection
```bash
# Set environment variables first (if not using .env file)
export SQLSERVER_HOST="your-server"
export SQLSERVER_USER="your-username"
export SQLSERVER_PASSWORD="your-password"
# Test the connection
mcp-sqlserver
```
You should see:
```
MCP SQL Server initialized for your-server:1433
Database: your-database, User: your-username
MCP SQL Server running on stdio
```
## Client Configuration
### Claude Desktop
1. **Find your config file:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`
2. **Add the server configuration:**
```json
{
"mcpServers": {
"sqlserver": {
"command": "mcp-sqlserver",
"env": {
"SQLSERVER_HOST": "your-server.database.windows.net",
"SQLSERVER_USER": "your-username",
"SQLSERVER_PASSWORD": "your-password",
"SQLSERVER_DATABASE": "your-database",
"SQLSERVER_ENCRYPT": "true",
"SQLSERVER_TRUST_CERT": "false"
}
}
}
}
```
3. **Restart Claude Desktop**
4. **Test in Claude:**
- "Test the SQL Server connection"
- "List all databases"
- "Show tables in the database"
### Claude Code CLI
```bash
# Set environment variables
export SQLSERVER_HOST="your-server"
export SQLSERVER_USER="your-username"
export SQLSERVER_PASSWORD="your-password"
# Add to Claude Code
claude mcp add sqlserver mcp-sqlserver
```
### VSCode
1. Install the MCP extension for VSCode
2. Add server configuration in VSCode settings
3. Reference the `mcp-sqlserver` command
## Common Configuration Examples
### Azure SQL Database
```env
SQLSERVER_HOST=your-server.database.windows.net
SQLSERVER_PORT=1433
SQLSERVER_ENCRYPT=true
SQLSERVER_TRUST_CERT=false
```
### On-Premises SQL Server with Self-Signed Certificate
```env
SQLSERVER_HOST=sql-server.company.com
SQLSERVER_PORT=1433
SQLSERVER_ENCRYPT=true
SQLSERVER_TRUST_CERT=true
```
### SQL Server Express (Local Development)
```env
SQLSERVER_HOST=localhost\\SQLEXPRESS
SQLSERVER_PORT=1433
SQLSERVER_ENCRYPT=false
SQLSERVER_TRUST_CERT=true
```
### Docker SQL Server
```env
SQLSERVER_HOST=localhost
SQLSERVER_PORT=1433
SQLSERVER_USER=sa
SQLSERVER_ENCRYPT=false
SQLSERVER_TRUST_CERT=true
```
## Environment Variables Reference
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SQLSERVER_HOST` | ✅ | - | SQL Server hostname or IP |
| `SQLSERVER_USER` | ✅ | - | Database username |
| `SQLSERVER_PASSWORD` | ✅ | - | Database password |
| `SQLSERVER_DATABASE` | ❌ | `master` | Default database |
| `SQLSERVER_PORT` | ❌ | `1433` | SQL Server port |
| `SQLSERVER_ENCRYPT` | ❌ | `true` | Enable TLS encryption |
| `SQLSERVER_TRUST_CERT` | ❌ | `true` | Trust server certificate |
| `SQLSERVER_CONNECTION_TIMEOUT` | ❌ | `30000` | Connection timeout (ms) |
| `SQLSERVER_REQUEST_TIMEOUT` | ❌ | `60000` | Query timeout (ms) |
| `SQLSERVER_MAX_ROWS` | ❌ | `1000` | Max rows per query |
## Troubleshooting
### Installation Issues
**"npm command not found"**
- Install Node.js from [nodejs.org](https://nodejs.org/)
**"Permission denied"**
- Use `sudo` for global installation: `sudo npm install -g ...`
- Or use local installation instead
**"Package not found"**
- Ensure you're using the correct package name: `@modelcontextprotocol/server-sqlserver`
### Connection Issues
**"Failed to connect"**
1. Verify server hostname and port
2. Check network connectivity: `telnet your-server 1433`
3. Verify SQL Server is running and accepting connections
4. Check firewall settings
**"Login failed"**
1. Verify username and password
2. Check if SQL Server authentication is enabled
3. Ensure user has necessary permissions
**"Certificate validation failed"**
- Set `SQLSERVER_TRUST_CERT=true` for self-signed certificates
- For production: Use proper SSL certificates
**"Timeout errors"**
- Increase `SQLSERVER_CONNECTION_TIMEOUT`
- Check network latency
- Verify SQL Server performance
### Permission Issues
**"Permission denied on database"**
- Grant `db_datareader` role to user
- Ensure user has `CONNECT` permission
**"Invalid object name"**
- Check table exists in specified database
- Verify schema names are correct
- Ensure user has access to system views
## Support
- **Documentation**: See README.md for detailed usage
- **Examples**: Check the `examples/` directory
- **Issues**: Report problems on GitHub
- **Security**: Only use read-only database accounts
## Next Steps
1. ✅ Install the package
2. ✅ Configure environment variables
3. ✅ Test connection
4. ✅ Configure your MCP client
5. 🎉 Start exploring your databases with AI!
Happy querying! 🚀