Wener/mssql MCP

1# @wener/mssql-mcp
2 
3A powerful Microsoft SQL Server MCP (Model Context Protocol) server that enables Claude Desktop to interact with SQL Server databases through natural language queries.
4 
5[![npm version](https://badge.fury.io/js/%40wener%2Fmssql-mcp.svg)](https://www.npmjs.com/package/@wener/mssql-mcp)
6[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
7 
8## 🚀 Quick Start
9 
10### Install and Run with npx (Recommended)
11 
12```bash
13# Run directly without installation
14npx @wener/mssql-mcp --help
15 
16# Start with environment variables
17MSSQL_SERVER=localhost MSSQL_DATABASE=mydb MSSQL_USER=sa MSSQL_PASSWORD=password npx @wener/mssql-mcp --stdio
18 
19# Start with environment file
20npx @wener/mssql-mcp --env-file .env --stdio
21```
22 
23### Global Installation
24 
25```bash
26# Install globally
27npm install -g @wener/mssql-mcp
28 
29# Run from anywhere
30mssql-mcp --help
31```
32 
33## ✨ Features
34 
35- 🤖 **AI-Ready**: Seamless integration with Claude Desktop and MCP protocol
36- 🔍 **Smart Queries**: Execute SQL queries in CSV or JSON format through natural language
37- 🔐 **Secure Authentication**: Support for SQL Server Auth, Windows Auth, and Azure SQL
38- 🏢 **Enterprise Ready**: LocalDB, Azure SQL Database, and SQL Server 2008+ support
39- 📊 **Data Access**: Browse database tables and their contents automatically
40- 🚀 **Zero Config**: Single executable with all dependencies bundled
41- 🛡️ **Read-Only Mode**: Optional safety mode for production databases
42 
43## 🏗️ Setup for Claude Desktop
44 
45### 1. Create Environment File
46 
47Create a `.env` file with your database credentials:
48 
49```bash
50# Required: Database connection
51MSSQL_SERVER=localhost
52MSSQL_DATABASE=AdventureWorks2019
53MSSQL_USER=sa
54MSSQL_PASSWORD=YourPassword123
55 
56# Optional: Security and performance
57MSSQL_ACCESS_MODE=readonly  # Use 'readonly' for safe querying
58MSSQL_ENCRYPT=false         # Set 'true' for Azure SQL
59```
60 
61### 2. Configure Claude Desktop
62 
63Add to your `claude_desktop_config.json`:
64 
65```json
66{
67  "mcpServers": {
68    "mssql": {
69      "command": "npx",
70      "args": ["@wener/mssql-mcp", "--env-file", "/path/to/your/.env", "--stdio"]
71    }
72  }
73}
74```
75 
76### 3. Restart Claude Desktop
77 
78Your SQL Server database is now available to Claude! 🎉
79 
80## 📋 Environment Configuration
81 
82### SQL Server Authentication
83 
84```bash
85MSSQL_SERVER=localhost
86MSSQL_DATABASE=your_database
87MSSQL_USER=your_username
88MSSQL_PASSWORD=your_password
89```
90 
91### Windows Authentication
92 
93```bash
94MSSQL_SERVER=localhost
95MSSQL_DATABASE=your_database
96MSSQL_WINDOWS_AUTH=true
97```
98 
99### Azure SQL Database
100 
101```bash
102MSSQL_SERVER=yourserver.database.windows.net
103MSSQL_DATABASE=your_database
104MSSQL_USER=your_username
105MSSQL_PASSWORD=your_password
106# MSSQL_ENCRYPT=true (automatically enabled for Azure SQL)
107```
108 
109### LocalDB
110 
111```bash
112MSSQL_SERVER=(localdb)\\MSSQLLocalDB
113MSSQL_DATABASE=MyLocalDatabase
114MSSQL_WINDOWS_AUTH=true
115```
116 
117### Advanced Options
118 
119```bash
120# Port (default: 1433)
121MSSQL_PORT=1433
122 
123# Force encryption (default: false, auto-enabled for Azure SQL)
124MSSQL_ENCRYPT=true
125 
126# Access mode: 'readonly' or 'readwrite' (default: readwrite)
127MSSQL_ACCESS_MODE=readonly
128```
129 
130## 🛠️ Available Tools
131 
132When connected, Claude can use these capabilities:
133 
134### 📊 SQL Query Execution
135 
136- **`exec_sql_csv`**: Execute SQL queries and get results in CSV format
137- **`exec_sql_json`**: Execute SQL queries and get results in JSON format
138- **`get_version`**: Get SQL Server version information _(readOnlyHint: true)_
139 
140### 📂 Database Resources
141 
142- **Table Discovery**: Automatically lists all available tables
143- **Table Data Access**: Browse table contents (top 100 rows per table)
144- **Schema Information**: Access table structures and metadata
145 
146## 🛡️ Security Features
147 
148### Read-Only Mode
149 
150For production databases, use read-only mode:
151 
152```bash
153MSSQL_ACCESS_MODE=readonly
154```
155 
156This restricts operations to:
157- `SELECT` statements
158- `WITH` (Common Table Expressions)
159- `SHOW`, `DESCRIBE`, `EXPLAIN`, `DESC` commands
160 
161### Built-in Protection
162 
163- ✅ SQL injection prevention through parameterized queries
164- ✅ Table name validation and escaping
165- ✅ Connection encryption for Azure SQL (auto-detected)
166- ✅ Secure credential handling
167 
168## 🎯 Usage Examples
169 
170### Ask Claude to Query Your Database
171 
172> "Show me the top 10 customers by total sales from the database"
173 
174> "What tables are available in this database?"
175 
176> "Create a summary report of inventory levels by category"
177 
178> "Find all orders placed in the last 30 days"
179 
180Claude will automatically:
1811. 🔍 Explore available tables
1822. 📝 Write appropriate SQL queries
1833. 📊 Execute queries and format results
1844. 📈 Analyze and explain the data
185 
186## 🚀 Command Line Usage
187 
188### STDIO Mode (Claude Desktop)
189 
190```bash
191mssql-mcp --stdio --env-file .env
192```
193 
194### HTTP Mode (Development)
195 
196```bash
197mssql-mcp --port 3003 --host localhost --env-file .env
198```
199 
200### Command Options
201 
202- `--stdio`: Use STDIO transport (required for Claude Desktop)
203- `--env-file <path>`: Load environment variables from file
204- `--port <port>`: HTTP server port (default: 3003)
205- `--host <host>`: HTTP server host (default: localhost)
206- `--verbose`: Enable detailed logging
207- `--help`: Show help information
208 
209## 🔧 Troubleshooting
210 
211### Connection Issues
212 
213```bash
214# Test connection
215mssql-mcp --verbose --env-file .env
216 
217# Check SQL Server is running
218sqlcmd -S localhost -U sa -P yourpassword -Q "SELECT @@VERSION"
219```
220 
221### Common Problems
222 
223**"Login failed"**: Check username, password, and database name
224**"Server not found"**: Verify `MSSQL_SERVER` and `MSSQL_PORT`
225**"SSL error"**: Set `MSSQL_ENCRYPT=false` for local development
226**"Permission denied"**: Ensure user has database access permissions
227 
228### Debug Mode
229 
230```bash
231# Enable verbose logging
232mssql-mcp --verbose --stdio --env-file .env
233```
234 
235## 📚 Example Databases
236 
237### AdventureWorks (Learning)
238 
239Perfect for testing and learning:
240 
2411. Download [AdventureWorks backup files](https://github.com/Microsoft/sql-server-samples/releases/tag/adventureworks)
2422. Restore to your SQL Server instance
2433. Configure connection:
244 
245```bash
246MSSQL_SERVER=localhost
247MSSQL_DATABASE=AdventureWorks2019
248MSSQL_USER=sa
249MSSQL_PASSWORD=YourPassword123
250MSSQL_ACCESS_MODE=readonly  # Safe for exploration
251```
252 
253### Northwind (Classic)
254 
255Great for business scenarios:
256 
257```bash
258MSSQL_SERVER=localhost
259MSSQL_DATABASE=Northwind
260MSSQL_USER=sa
261MSSQL_PASSWORD=YourPassword123
262```
263 
264## 🏢 Enterprise Features
265 
266- **SQL Server 2008+ Compatibility**: Works with legacy systems
267- **Connection Pooling**: Automatic connection management
268- **High Availability**: Supports SQL Server clusters and availability groups
269- **Multi-Database**: Connect to different databases by changing configuration
270- **Audit Trail**: All queries are logged for security compliance
271 
272## 📄 License
273 
274MIT License - feel free to use in personal and commercial projects.
275 
276## 🤝 Contributing
277 
278Issues and feature requests are welcome on [GitHub](https://github.com/wenerme/wode).
279 
280## 🔗 Related Projects
281 
282- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
283- [Claude Desktop](https://claude.ai/download) - AI assistant with MCP support
284- [Microsoft SQL Server](https://www.microsoft.com/sql-server/) - Database platform
285 
286---
287 
288**Made with ❤️ for the AI and SQL Server community**
289