MoMitwalyIgniteTech/mssql-mcp-server

MSSQL Database MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact directly and securely with Microsoft SQL Server databases using Basic SQL Authentication.

🚀 Features

• Basic SQL Authentication - Connect using username/password (no Azure AD required)
• Secure Query Execution - Built-in SQL injection protection and query validation
• Multiple Database Operations - Read, write, create tables, manage indexes
• Read-Only Mode - Safe mode for production environments
• Cross-Platform - Works on Windows, macOS, and Linux
• AI Assistant Integration - Compatible with Claude Desktop, VS Code Agent, and other MCP clients

🛠️ Installation

Prerequisites

• Node.js 14 or higher
• Access to a Microsoft SQL Server database
• An MCP-compatible AI assistant (Claude Desktop, VS Code Agent, etc.)

Setup

1. Clone the repository

   git clone https://github.com/yourusername/mssql-mcp-server.git
   cd mssql-mcp-server
   

2. Install dependencies

   npm install
   

3. Build the project

   npm run build
   

⚙️ Configuration

Claude Desktop Setup

1. Open Claude Desktop settings: File → Settings → Developer → Edit Config
2. Add the following configuration:

{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["/path/to/your/mssql-mcp-server/dist/index.js"],
      "env": {
        "SERVER_NAME": "your-server.database.windows.net",
        "DATABASE_NAME": "your-database-name",
        "SQL_USERNAME": "your-username",
        "SQL_PASSWORD": "your-password",
        "READONLY": "true",
        "CONNECTION_TIMEOUT": "30",
        "TRUST_SERVER_CERTIFICATE": "false"
      }
    }
  }
}

VS Code Agent Setup

1. Create .vscode/mcp.json in your workspace:

{
  "mcp": {
    "servers": {
      "mssql": {
        "type": "stdio",
        "command": "node",
        "args": ["/path/to/your/mssql-mcp-server/dist/index.js"],
        "env": {
          "SERVER_NAME": "your-server.database.windows.net",
          "DATABASE_NAME": "your-database-name",
          "SQL_USERNAME": "your-username",
          "SQL_PASSWORD": "your-password",
          "READONLY": "true"
        }
      }
    }
  }
}

Environment Variables

🔧 Available Tools

Read-Only Mode (READONLY: "true")

• read_data - Execute SELECT queries
• list_table - List all tables in the database
• describe_table - Get detailed table schema information

Full Access Mode (READONLY: "false")

All read-only tools plus:

• insert_data - Insert new records into tables
• update_data - Update existing records
• create_table - Create new tables
• create_index - Create database indexes
• drop_table - Delete tables

💡 Usage Examples

Once configured, you can interact with your database using natural language:

"Show me all customers from New York"
"Create a table for storing product information"
"List all tables in the database"
"Describe the structure of the users table"
"Insert a new customer record"

🔒 Security Features

• SQL Injection Protection - All queries are validated and sanitized
• Read-Only Mode - Safely explore databases without modification risk
• Query Validation - Dangerous operations and patterns are blocked
• Connection Security - SSL encryption enabled by default
• WHERE Clause Requirements - SELECT and UPDATE operations require WHERE clauses

🏗️ Development

Build

npm run build

Watch Mode

npm run watch

Start Server

npm start

🐛 Troubleshooting

Common Issues

Connection Errors

• Verify server name, database name, and credentials
• Check network connectivity to the SQL Server
• Ensure SQL Server allows the authentication method

Module Not Found (Windows + WSL)

• Use the full Windows path: C:\\path\\to\\dist\\index.js
• Or copy the server to a Windows directory

Permission Denied

• Verify the SQL user has appropriate database permissions
• Check if the database requires specific authentication methods

Debug Mode

Add this to your environment variables for detailed logging:

"DEBUG": "true"

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Built using the Model Context Protocol
• Uses the mssql Node.js package
• Compatible with Claude Desktop and VS Code Agent

📞 Support

• Create an issue for bug reports or feature requests
• Check the MCP documentation for general MCP questions
• Review the troubleshooting section for common problems

Made with ❤️ for the AI community