MS SQL MCP Server 1.1
An easy-to-use bridge that lets AI assistants like Claude directly query and explore Microsoft SQL Server databases. No coding experience required!
What Does This Tool Do?
This tool allows AI assistants to:
Discover tables in your SQL Server database
View table structures (columns, data types, etc.)
Execute read-only SQL queries safely
Generate SQL queries from natural language requests
🌟 Why You Need This Tool
Bridge the Gap Between Your Data and AI
No Coding Required: Give Claude and other AI assistants direct access to your SQL Server databases without writing complex integration code
Maintain Control: All queries are read-only by default, ensuring your data remains safe
Private & Secure: Your database credentials stay local and are never sent to external services
Practical Benefits
Save Hours of Manual Work: No more copy-pasting data or query results to share with AI
Deeper Analysis: AI can navigate your entire database schema and provide insights across multiple tables
Natural Language Interface: Ask questions about your data in plain English
End the Context Limit Problem: Access large datasets that would exceed normal AI context windows
Perfect For
Data Analysts who want AI help interpreting SQL data without sharing credentials
Developers looking for a quick way to explore database structure through natural conversation
Business Analysts who need insights without SQL expertise
Database Administrators who want to provide controlled access to AI tools
🚀 Quick Start Guide
Step 1: Install Prerequisites
Install Node.js (version 14 or higher)
Have access to a Microsoft SQL Server database (on-premises or Azure)
Step 2: Clone and Setup
Step 3: Configure Your Database Connection
Edit the .env
file with your database credentials:
Step 4: Start the Server
Step 5: Try it out!
📊 Example Use Cases
Explore your database structure without writing SQL
mcp_SQL_mcp_discover_database()Get detailed information about a specific table
mcp_SQL_mcp_table_details({ tableName: "Customers" })Run a safe query
mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Customers", returnResults: true })Find tables by name pattern
mcp_SQL_mcp_discover_tables({ namePattern: "%user%" })Use pagination to navigate large result sets
// First page mcp_SQL_mcp_execute_query({ sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY", returnResults: true }) // Next page mcp_SQL_mcp_execute_query({ sql: "SELECT * FROM Users ORDER BY Username OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY", returnResults: true })Cursor-based pagination for optimal performance
// First page mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users ORDER BY Username", returnResults: true }) // Next page using the last value as cursor mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users WHERE Username > 'last_username' ORDER BY Username", returnResults: true })Ask natural language questions
"Show me the top 5 customers with the most orders in the last month"
💡 Real-World Applications
For Business Intelligence
Sales Performance Analysis: "Show me monthly sales trends for the past year and identify our top-performing products by region."
Customer Segmentation: "Analyze our customer base by purchase frequency, average order value, and geographical location."
Financial Reporting: "Create a quarterly profit and loss report comparing this year to last year."
For Database Management
Schema Optimization: "Help me identify tables with missing indexes by examining query performance data."
Data Quality Auditing: "Find all customer records with incomplete information or invalid values."
Usage Analysis: "Show me which tables are most frequently accessed and what queries are most resource-intensive."
For Development
API Exploration: "I'm building an API - help me analyze the database schema to design appropriate endpoints."
Query Optimization: "Review this complex query and suggest performance improvements."
Database Documentation: "Create comprehensive documentation of our database structure with explanations of relationships."
🖥️ Interactive Client Features
The bundled client provides an easy menu-driven interface:
List available resources - See what information is available
List available tools - See what actions you can perform
Execute SQL query - Run a read-only SQL query
Get table details - View structure of any table
Read database schema - See all tables and their relationships
Generate SQL query - Convert natural language to SQL
🧠 Effective Prompting & Tool Usage Guide
When working with Claude or other AI assistants through this MCP server, the way you phrase your requests significantly impacts the results. Here's how to help the AI use the database tools effectively:
Basic Tool Call Format
When prompting an AI to use this tool, follow this structure:
Essential Commands & Syntax
Here are the main tools and their correct syntax:
When to use each tool:
Database Discovery: Start with this when the AI is unfamiliar with your database structure.
Table Details: Use when focusing on a specific table before writing queries.
Query Execution: When you need to retrieve or analyze actual data.
Table Discovery by Pattern: When looking for tables related to a specific domain.
Effective Prompting Patterns
Step-by-Step Workflows
For complex tasks, guide the AI through a series of steps:
Structure First, Then Query
Ask for Explanations
SQL Server Dialect Notes
Remind the AI about SQL Server's specific syntax:
Correcting Tool Usage
If the AI uses incorrect syntax, you can help it with:
Troubleshooting Through Prompts
If the AI is struggling with a database task, try these approaches:
Be more specific about tables: "Before writing that query, please check if the CustomerOrders table exists and what columns it has."
Break complex tasks into steps: "Let's approach this step by step. First, look at the Products table structure. Then, check the Orders table..."
Ask for intermediate results: "Run a simple query on that table first so we can verify the data format before trying more complex analysis."
Request query explanations: "After writing this query, explain what each part does so I can verify it's doing what I need."
🔎 Advanced Query Capabilities
Table Discovery & Exploration
The MCP Server provides powerful tools for exploring your database structure:
Pattern-based table discovery: Find tables matching specific patterns
mcp_SQL_mcp_discover_tables({ namePattern: "%order%" })Schema overview: Get a high-level view of tables by schema
mcp_SQL_mcp_execute_query({ sql: "SELECT TABLE_SCHEMA, COUNT(*) AS TableCount FROM INFORMATION_SCHEMA.TABLES GROUP BY TABLE_SCHEMA" })Column exploration: Examine column metadata for any table
mcp_SQL_mcp_table_details({ tableName: "dbo.Users" })
Pagination Techniques
The server supports multiple pagination methods for handling large datasets:
Offset/Fetch Pagination: Standard SQL pagination using OFFSET and FETCH
mcp_SQL_mcp_execute_query({ sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY" })Cursor-Based Pagination: More efficient for large datasets
// Get first page mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users ORDER BY Username" }) // Get next page using last value as cursor mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users WHERE Username > 'last_username' ORDER BY Username" })Count with Data: Retrieve total count alongside paginated data
mcp_SQL_mcp_execute_query({ sql: "WITH TotalCount AS (SELECT COUNT(*) AS Total FROM Users) SELECT TOP 10 u.*, t.Total FROM Users u CROSS JOIN TotalCount t ORDER BY Username" })
Complex Joins & Relationships
Explore relationships between tables with join operations:
Analytical Queries
Run aggregations and analytical queries to gain insights:
Using SQL Server Features
The MCP server supports SQL Server-specific features:
Common Table Expressions (CTEs)
Window functions
JSON operations
Hierarchical queries
Full-text search (when configured in your database)
🔗 Integration Options
Claude Desktop Integration
Connect this tool directly to Claude Desktop in a few easy steps:
Install Claude Desktop from anthropic.com
Edit Claude's configuration file:
Location:
~/Library/Application Support/Claude/claude_desktop_config.json
Add this configuration:
Replace
/FULL/PATH/TO/
with the actual path to where you cloned this repositoryRestart Claude Desktop
Look for the tools icon in Claude Desktop - you can now use database commands directly!
Connecting with Cursor IDE
Cursor is an AI-powered code editor that can leverage this tool for advanced database interactions. Here's how to set it up:
Setup in Cursor
Open Cursor IDE (download from cursor.sh if you don't have it)
Start the MS SQL MCP Server using the HTTP/SSE transport:
npm run start:sseCreate a new workspace or open an existing project in Cursor
Enter Cursor Settings
Click MCP
Add new MCP server
Name your MCP server, select type: sse
Enter server URL as: localhost:3333/sse (or the port you have it running on)
Using Database Commands in Cursor
Once connected, you can use MCP commands directly in Cursor's AI chat:
Ask Claude in Cursor to explore your database:
Can you show me the tables in my database?Execute specific queries:
Query the top 10 records from the Customers tableGenerate and run complex queries:
Find all orders from the last month with a value over $1000
Troubleshooting Cursor Connection
Make sure the MS SQL MCP Server is running with the HTTP/SSE transport
Check that the port is correct and matches what's in your .env file
Ensure your firewall isn't blocking the connection
If using a different IP/hostname, update the SERVER_URL in your .env file
🔄 Transport Methods Explained
Option 1: stdio Transport (Default)
Best for: Using directly with Claude Desktop or the bundled client
Option 2: HTTP/SSE Transport
Best for: Network access or when used with web applications
🛡️ Security Features
Read-only by default: No risk of data modification
Private credentials: Database connection details stay in your
.env
fileSQL injection protection: Built-in validation for SQL queries
🔎 Troubleshooting for New Users
"Cannot connect to database"
Check your
.env
file for correct database credentialsMake sure your SQL Server is running and accepting connections
For Azure SQL, verify your IP is allowed in the firewall settings
"Module not found" errors
Run
npm install
again to ensure all dependencies are installedMake sure you're using Node.js version 14 or higher
"Transport error" or "Connection refused"
For HTTP/SSE transport, verify the PORT in your .env is available
Make sure no firewall is blocking the connection
Claude Desktop can't connect
Double-check the path in your
claude_desktop_config.json
Ensure you're using absolute paths, not relative ones
Restart Claude Desktop completely after making changes
📚 Understanding SQL Server Basics
If you're new to SQL Server, here are some key concepts:
Tables: Store your data in rows and columns
Schemas: Logical groupings of tables (like folders)
Queries: Commands to retrieve or analyze data
Views: Pre-defined queries saved for easy access
This tool helps you explore all of these without needing to be a SQL expert!
🏗️ Architecture & Core Modules
The MS SQL MCP Server is built with a modular architecture that separates concerns for maintainability and extensibility:
Core Modules
database.mjs
- Database Connectivity
Manages SQL Server connection pooling
Provides query execution with retry logic and error handling
Handles database connections, transactions, and configuration
Includes utilities for sanitizing SQL and formatting errors
tools.mjs
- Tool Registration
Registers all database tools with the MCP server
Implements tool validation and parameter checking
Provides core functionality for SQL queries, table exploration, and database discovery
Maps tool calls to database operations
resources.mjs
- Database Resources
Exposes database metadata through resource endpoints
Provides schema information, table listings, and procedure documentation
Formats database structure information for AI consumption
Includes discovery utilities for database exploration
pagination.mjs
- Results Navigation
Implements cursor-based pagination for large result sets
Provides utilities for generating next/previous page cursors
Transforms SQL queries to support pagination
Handles SQL Server's OFFSET/FETCH pagination syntax
errors.mjs
- Error Handling
Defines custom error types for different failure scenarios
Implements JSON-RPC error formatting
Provides human-readable error messages
Includes middleware for global error handling
logger.mjs
- Logging System
Configures Winston logging with multiple transports
Provides context-aware request logging
Handles log rotation and formatting
Captures uncaught exceptions and unhandled rejections
How These Modules Work Together
When a tool call is received, the MCP server routes it to the appropriate handler in
tools.mjs
The tool handler validates parameters and constructs a database query
The query is executed via functions in
database.mjs
, with possible pagination frompagination.mjs
Results are formatted and returned to the client
Any errors are caught and processed through
errors.mjs
All operations are logged via
logger.mjs
This architecture ensures:
Clean separation of concerns
Consistent error handling
Comprehensive logging
Efficient database connection management
Scalable query execution
⚙️ Environment Configuration Explained
The .env
file controls how the MS SQL MCP Server connects to your database and operates. Here's a detailed explanation of each setting:
Connection Types Explained
stdio Transport
Use when connecting directly with Claude Desktop
Communication happens through standard input/output streams
Set
TRANSPORT=stdio
in your .env fileRun with
npm start
HTTP/SSE Transport
Use when connecting over a network (like with Cursor IDE)
Uses Server-Sent Events (SSE) for real-time communication
Set
TRANSPORT=sse
in your .env fileConfigure
SERVER_URL
to match your server addressRun with
npm run start:sse
SQL Server Connection Examples
Local SQL Server
Azure SQL Database
Query Results Storage
Query results are saved as JSON files in the directory specified by QUERY_RESULTS_PATH
. This prevents large result sets from overwhelming the conversation. You can:
Leave this blank to use the default
query-results
directory in the projectSet a custom path like
/Users/username/Documents/query-results
Access saved results using the provided UUID in the tool response
📝 License
ISC
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A bridge that allows AI assistants like Claude to directly query and explore Microsoft SQL Server databases without requiring coding experience.
- What Does This Tool Do?
- 🌟 Why You Need This Tool
- 🚀 Quick Start Guide
- 📊 Example Use Cases
- 💡 Real-World Applications
- 🖥️ Interactive Client Features
- 🧠 Effective Prompting & Tool Usage Guide
- 🔎 Advanced Query Capabilities
- 🔗 Integration Options
- 🔄 Transport Methods Explained
- 🛡️ Security Features
- 🔎 Troubleshooting for New Users
- 📚 Understanding SQL Server Basics
- 🏗️ Architecture & Core Modules
- ⚙️ Environment Configuration Explained
- 📝 License
Related MCP Servers
- AsecurityAlicenseAqualityAllows AI assistants to list tables, read data, and execute SQL queries through a controlled interface, making database exploration and analysis safer and more structured.Last updated -898MIT License
- AsecurityAlicenseAqualityBridges Claude AI with Xcode, enabling AI-powered code assistance, project management, and automated development tasks securely on your local machine.Last updated -18319MIT License
- AsecurityFlicenseAqualityThe server connects the Claude AI to the internet through the capabilites of the LSD SQL language, turning web data into a queryable database-like structure to interact with real-world data efficiently.Last updated -464
- AsecurityAlicenseAqualityAn easy-to-use bridge that lets AI assistants like Claude and Cursor IDE directly query and explore Microsoft SQL Server databases. No coding experience required!Last updated -338164GPL 3.0