Microsoft SQL MCP server
Lets an AI client explore SQL Server schemas and run read-only SELECT queries safely.
Also known as bilims/mcp-sqlserver, @bilims/mcp-sqlserver
- Stars
- 47
- Tools
- 8
- Downloads, 30 days
- 4,376
- Latest version
- —
- Last commit
- Mar 31, 2026
- License
- MIT
What is Microsoft SQL MCP?
Microsoft SQL lets an AI client explore SQL Server schemas and run read-only SELECT queries safely. It exposes 8 tools, such as list_databases, list_tables, list_views.
Summary generated from the project's README
About Microsoft SQL MCP server
Exploring Microsoft SQL Server schemas and running read-only queries from an AI client is what this server enables. It allows developers and data analysts to interact with Azure SQL Database, on-premises SQL Server, or local SQL Server Express instances using natural language through tools like Claude Desktop or Claude Code CLI. The server functions by connecting to your database via environment variables such as host, user, password, and database name.
Security is a primary focus, as the server restricts operations to read-only SELECT statements to prevent accidental data modification. It includes built-in protections against SQL injection and uses a blacklist to block dangerous keywords like INSERT or DELETE. Users can discover database structures using tools like list_tables, describe_table, and get_foreign_keys. For data retrieval, the execute_query tool allows for safe exploration with configurable row limits and timeouts to ensure stability during complex queries.
What you can do with it
- 1Explore database structuresAsk the AI to identify all tables and their column definitions within a specific database schema.
- 2Analyze table relationshipsRequest a summary of how different tables are connected through foreign keys.
- 3Retrieve sample dataUse natural language to fetch a limited set of records from a specific table for inspection.
- 4Audit table sizesIdentify which tables in the database are consuming the most space or contain the most rows.
Written from the project's README. Every use case is checked against a quote from it.
How to install Microsoft SQL MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Microsoft SQL MCP in Claude Code
$ claude mcp add mcp-sqlserver -- npx -y @bilims/mcp-sqlserverInstall Microsoft SQL MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-sqlserver": {
"command": "npx",
"args": [
"-y",
"@bilims/mcp-sqlserver"
]
}
}
}Install Microsoft SQL MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-sqlserver": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@bilims/mcp-sqlserver"
]
}
}
}Install Microsoft SQL MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-sqlserver","type":"stdio","command":"npx","args":["-y","@bilims/mcp-sqlserver"]}'Install Microsoft SQL MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-sqlserver": {
"command": "npx",
"args": [
"-y",
"@bilims/mcp-sqlserver"
]
}
}
}Install Microsoft SQL MCP in Codex
$ codex mcp add mcp-sqlserver -- npx -y @bilims/mcp-sqlserverInstall Microsoft SQL MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-sqlserver] command = "npx" args = ["-y", "@bilims/mcp-sqlserver"]
Install Microsoft SQL MCP in Gemini CLI
$ gemini mcp add -s user mcp-sqlserver npx -- -y @bilims/mcp-sqlserverInstall Microsoft SQL MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-sqlserver": {
"command": "npx",
"args": [
"-y",
"@bilims/mcp-sqlserver"
]
}
}
}Microsoft SQL MCP tools 8
Detected from the READMElist_databaseslist_tableslist_viewsdescribe_tableget_foreign_keysget_table_statsexecute_queryget_server_info
| list_databases | — | |
| list_tables | — | |
| list_views | — | |
| describe_table | — | |
| get_foreign_keys | — | |
| get_table_stats | — | |
| execute_query | — | |
| get_server_info | — |
Configuration
SQLSERVER_DATABASESQLSERVER_ENCRYPTSQLSERVER_HOSTSQLSERVER_PASSWORDSQLSERVER_TRUST_CERTSQLSERVER_USER
| Name | Description | |
|---|---|---|
| SQLSERVER_DATABASE | — | |
| SQLSERVER_ENCRYPT | — | |
| SQLSERVER_HOST | — | |
| SQLSERVER_PASSWORD | — | |
| SQLSERVER_TRUST_CERT | — | |
| SQLSERVER_USER | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablebilims/mcp-sqlserver is public and reachablegithub.com/bilims/mcp-sqlserver ↗Pass
- Package names this repository as its source@bilims/mcp-sqlserver names bilims/mcp-sqlserver as sourcenpmjs.com/package/@bilims/mcp-sqlserver ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-03-31github.com/bilims/mcp-sqlserver ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @bilims/mcp-sqlserverPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model8 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMCP SQL Server
A read-only Model Context Protocol (MCP) server for Microsoft SQL Server that enables AI agents to safely explore and query SQL Server databases.
Quick Start
Step 1: Install the Package
# Global installation (recommended)
npm install -g @bilims/mcp-sqlserver
# Verify installation
mcp-sqlserver --version
Step 2: Configure Your SQL Server Connection
Choose your SQL Server type and follow the configuration:
Azure SQL Database
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"
On-Premises SQL Server
export SQLSERVER_HOST="your-sql-server.company.com"
export SQLSERVER_USER="your-username"
export SQLSERVER_PASSWORD="your-password"
export SQLSERVER_DATABASE="your-database"
export SQLSERVER_ENCRYPT="true"
export SQLSERVER_TRUST_CERT="true" # For self-signed certificates
Local SQL Server Express
export SQLSERVER_HOST="localhost\\SQLEXPRESS"
export SQLSERVER_USER="sa"
export SQLSERVER_PASSWORD="your-password"
export SQLSERVER_DATABASE="master"
export SQLSERVER_ENCRYPT="false"
export SQLSERVER_TRUST_CERT="true"
Step 3: Test the Connection
# Test your configuration
mcp-sqlserver --help
# Quick connection test (press Ctrl+C to exit)
mcp-sqlserver
Step 4: Add to Claude Desktop
-
Find your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
-
Add the MCP server configuration:
{
"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"
}
}
}
}
- Restart Claude Desktop
Step 5: Start Exploring!
Try these commands in Claude Desktop:
"Test the SQL Server connection""List all databases on the server""Show me the tables in [database name]""Describe the structure of the Users table""Show me foreign key relationships"
Features
- 🔒 Read-only operations: Only SELECT queries allowed, with comprehensive security validation
- 🗄️ Schema discovery: Explore databases, tables, views, relationships, and metadata
- 📊 Data exploration: Execute safe queries with built-in limits and timeouts
- 🔐 Enterprise-ready: Encrypted connections with certificate trust for production environments
- 🛡️ Security-first: Query validation, SQL injection protection, and access controls
Available Tools
Schema Discovery
list_databases- List all databases on the SQL Server instancelist_tables- List tables in a database or schemalist_views- List views in a database or schemadescribe_table- Get detailed table schema including columns, data types, and constraints
Relationship Analysis
get_foreign_keys- Get foreign key relationships for tablesget_table_stats- Get table statistics including row counts and size information
Data Exploration
execute_query- Execute read-only SELECT queries with safety validationget_server_info- Get SQL Server version, edition, and configuration details
Common Commands for Claude Desktop
Once your MCP server is configured, try these natural language commands:
Getting Started Commands
"Test the SQL Server connection"
"Show me server information"
"List all databases on this server"
"What tables are in the [database name] database?"
Database Exploration
"Describe the structure of the Users table"
"Show me foreign key relationships in this database"
"What are the largest tables by row count?"
"Give me a sample of data from the Orders table"
Advanced Analysis
"Help me understand the relationship between Orders and Customers"
"Show me all lookup tables in this database"
"What columns contain date/time information?"
"Find tables that might contain user authentication data"
Custom Queries
"Run this query: SELECT TOP 10 * FROM Products WHERE Price > 100"
"Show me all customers created in the last 30 days"
"What are the different product categories in the database?"
Installation
npm install
npm run build
Configuration
The server is configured using environment variables:
Required
SQLSERVER_USER- SQL Server usernameSQLSERVER_PASSWORD- SQL Server password
Optional
SQLSERVER_HOST- Server hostname (default: localhost)SQLSERVER_DATABASE- Default database nameSQLSERVER_PORT- Port number (default: 1433)SQLSERVER_ENCRYPT- Enable encryption (default: true)SQLSERVER_TRUST_CERT- Trust server certificate (default: true)SQLSERVER_CONNECTION_TIMEOUT- Connection timeout in ms (default: 30000)SQLSERVER_REQUEST_TIMEOUT- Request timeout in ms (default: 60000)SQLSERVER_MAX_ROWS- Maximum rows per query (default: 1000)
Usage
Environment Variables
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="true"
Running the Server
npm start
Installation Options
Option 1: Global Installation (Recommended)
npm install -g @bilims/mcp-sqlserver
Option 2: Local Installation
npm install @bilims/mcp-sqlserver
npx mcp-sqlserver
Option 3: Run with npx (No Installation)
npx @bilims/mcp-sqlserver
Integration Examples
Claude Desktop
Add to your Claude Desktop configuration (claude_desktop_config.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"
}
}
}
}
Claude Code CLI
# Set environment variables
export SQLSERVER_HOST="your-server"
export SQLSERVER_USER="your-username"
export SQLSERVER_PASSWORD="your-password"
# Use with Claude Code
claude mcp add sqlserver mcp-sqlserver
VSCode with MCP Extension
Install the MCP extension for VSCode and add the server configuration.
Security Features
Query Validation
- Only SELECT, WITH, SHOW, DESCRIBE, and EXPLAIN statements allowed
- Comprehensive blacklist of dangerous keywords (INSERT, UPDATE, DELETE, DROP, etc.)
- SQL injection pattern detection
- Automatic query sanitization
Connection Security
- TLS/SSL encryption enabled by default
- Server certificate trust options for enterprise environments
- Connection pooling with timeout controls
- Configurable request timeouts
Result Limits
- Maximum row limits per query (configurable)
- Automatic TOP clause injection for SELECT queries
- Query execution time tracking
- Memory usage protection
Example Queries
Once connected, you can use the tools through your MCP client:
// List all databases
await callTool("list_databases", {});
// List tables in a specific schema
await callTool("list_tables", { schema: "dbo" });
// Get table schema details
await callTool("describe_table", {
table_name: "Users",
schema: "dbo"
});
// Execute a read-only query
await callTool("execute_query", {
query: "SELECT TOP 10 * FROM Users WHERE active = 1",
limit: 10
});
// Get foreign key relationships
await callTool("get_foreign_keys", {
table_name: "Orders"
});
Development
# Install dependencies
npm install
# Build the project
npm run build
# Run in development mode
npm run dev
# Run linting
npm run lint
# Run tests
npm test
Troubleshooting
Connection Issues
- Verify server hostname and port
- Check if encryption/certificate settings match your SQL Server configuration
- Ensure user has appropriate read permissions
- Test connection using SQL Server Management Studio first
Permission Issues
The user account needs at minimum:
CONNECTpermission to the databaseSELECTpermission on tables/views you want to query- Access to system views for metadata queries
Common SQL Server Configurations
Azure SQL Database
export SQLSERVER_HOST="your-server.database.windows.net"
export SQLSERVER_ENCRYPT="true"
export SQLSERVER_TRUST_CERT="false"
On-premises SQL Server with self-signed certificates
export SQLSERVER_HOST="sql-server.company.com"
export SQLSERVER_ENCRYPT="true"
export SQLSERVER_TRUST_CERT="true"
License
MIT
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
Support
For issues and questions:
- Check the troubleshooting section above
- Review SQL Server connection documentation
- Ensure MCP client compatibility
Built with the Model Context Protocol SDK for seamless AI integration.
Microsoft SQL MCP questions
How do I add Microsoft SQL MCP to Claude Code?
Run claude mcp add mcp-sqlserver -- npx -y @bilims/mcp-sqlserver in your terminal. Add --scope user to make it available in every project.
How do I add Microsoft SQL MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Microsoft SQL MCP provide?
It exposes 8 tools, including list_databases, list_tables, list_views, describe_table, get_foreign_keys.
Can this MCP server modify or delete data in SQL Server?
No, it is read-only: only SELECT, WITH, SHOW, DESCRIBE, and EXPLAIN statements are allowed and dangerous keywords are blacklisted.
How do I configure the SQL Server connection?
Set environment variables such as SQLSERVER_HOST, SQLSERVER_USER, SQLSERVER_PASSWORD, and SQLSERVER_DATABASE, plus encryption options.
What tools does the server provide for schema discovery?
It exposes list_databases, list_tables, list_views, and describe_table, plus relationship and query tools.
Does it work with Azure SQL Database?
Yes, with encryption enabled and certificate trust disabled for the Azure setup.
How many rows can a query return?
Rows are capped per query by SQLSERVER_MAX_ROWS, which defaults to 1000.