README.md•5.36 kB
# MSSQL MCP Server
A Model Context Protocol (MCP) server that enables LLMs like Claude to interact with Microsoft SQL Server databases through natural language.
## Features
- 🔍 Query your SQL Server database using natural language
- 📊 Read, insert, update, and delete data
- 🏗️ Create and manage tables and indexes
- 🔒 Secure connection handling with optional read-only mode
- ⚡ Direct TypeScript execution with tsx - no build step required
## Quick Start
### Option 1: Use directly from GitHub with npx (Recommended)
No installation needed! Just configure Claude Desktop:
#### Windows
Add to `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"mssql": {
"type": "stdio",
"command": "cmd",
"args": ["/c", "npx", "-y", "github:EvilPhatBoi/McpSqlServer"],
"env": {
"SERVER_NAME": "your-server.database.windows.net",
"DATABASE_NAME": "your-database",
"SQL_USERNAME": "your-username",
"SQL_PASSWORD": "your-password",
"PORT": "1433",
"ENCRYPT": "true",
"TRUST_SERVER_CERTIFICATE": "false",
"CONNECTION_TIMEOUT": "30",
"READONLY": "false"
}
}
}
}
```
#### macOS/Linux
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"mssql": {
"type": "stdio",
"command": "npx",
"args": ["-y", "github:EvilPhatBoi/McpSqlServer"],
"env": {
"SERVER_NAME": "your-server.database.windows.net",
"DATABASE_NAME": "your-database",
"SQL_USERNAME": "your-username",
"SQL_PASSWORD": "your-password",
"PORT": "1433",
"ENCRYPT": "true",
"TRUST_SERVER_CERTIFICATE": "false",
"CONNECTION_TIMEOUT": "30",
"READONLY": "false",
"DEBUG": "false"
}
}
}
}
```
**Note for legacy SQL Servers:** If you experience SSL/TLS connection issues with older SQL Server versions, try:
- `"ENCRYPT": "false"` to disable TLS/SSL encryption
- `"TRUST_SERVER_CERTIFICATE": "true"` to trust self-signed certificates
- `"CONNECTION_TIMEOUT": "60"` or higher for slower connections
- `"DEBUG": "true"` to see detailed connection logs
### Option 2: Clone and run locally
1. Clone the repository:
```bash
git clone https://github.com/EvilPhatBoi/McpSqlServer.git
cd McpSqlServer
```
2. Install dependencies:
```bash
npm install
```
3. Create `.env` file:
```bash
cp .env.example .env
# Edit .env with your database credentials
```
4. Configure Claude Desktop to point to your local installation:
```json
{
"mcpServers": {
"mssql": {
"type": "stdio",
"command": "npx",
"args": ["tsx", "C:/path/to/McpSqlServer/src/index.ts"],
"env": {
"SERVER_NAME": "your-server.database.windows.net",
"DATABASE_NAME": "your-database",
"SQL_USERNAME": "your-username",
"SQL_PASSWORD": "your-password"
}
}
}
}
```
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `SERVER_NAME` | SQL Server hostname | Required |
| `DATABASE_NAME` | Database name | Required |
| `SQL_USERNAME` | SQL username | Required |
| `SQL_PASSWORD` | SQL password | Required |
| `PORT` | SQL Server port | `1433` |
| `ENCRYPT` | Enable TLS/SSL encryption | `true` |
| `TRUST_SERVER_CERTIFICATE` | Trust self-signed certificates | `false` |
| `CONNECTION_TIMEOUT` | Connection timeout in seconds | `30` |
| `READONLY` | Enable read-only mode | `false` |
| `DEBUG` | Enable debug logging | `false` |
## Usage Examples
Once configured, you can interact with your database using natural language in Claude:
- "Show me all customers from New York"
- "Create a table called products with columns for id, name, and price"
- "Update the price of product with id 5 to 29.99"
- "List all tables in the database"
- "Describe the structure of the orders table"
## Development
### Running locally with tsx:
```bash
npm run start # Run the server
npm run dev # Run with watch mode
```
### Type checking:
```bash
npm run typecheck
```
## Security Notes
- Never commit `.env` files with real credentials
- Use read-only mode (`READONLY=true`) in production for safety
- The server requires WHERE clauses for updates to prevent accidental mass updates
- Consider using environment-specific credentials
## Troubleshooting
### Connection issues
- Ensure your SQL Server allows remote connections
- Check firewall rules for SQL Server port (default 1433, or your custom PORT setting)
- Verify credentials and server name
- Enable debug logging by setting `DEBUG=true` in your environment variables
### SSL/TLS connection issues
- For older SQL Server versions that don't support modern TLS, set `ENCRYPT=false`
- If using self-signed certificates, set `TRUST_SERVER_CERTIFICATE=true`
- For connection timeout issues, increase `CONNECTION_TIMEOUT` to 60 or higher
- Check that your SQL Server accepts the TLS version your Node.js supports
### Debug mode
To enable detailed logging for troubleshooting:
```json
"env": {
"DEBUG": "true",
// ... other environment variables
}
```
### Authentication errors
- This server uses SQL authentication, not Windows authentication
- Ensure SQL authentication is enabled on your server
- Check that the SQL user has appropriate permissions
## License
MIT