SQL Server MCP: Cross - platform Tool for AI to Query SQL DB via Natural Language

Sql MCP Mac Windows

SQL Server MCP is a cross - platform database integration tool designed for AI assistants, enabling them to explore and query SQL Server databases through natural language. It provides functions such as schema exploration, relationship mapping, and safe query execution, and supports Windows and macOS systems.

Database Developer tools #Database integration #AI assistant #SQL Server #Cross - platform .TypeScript

rating : 2 points

downloads : 5.6K

update time : 2025-12-29

Open Site

What is SQL Server MCP?

SQL Server MCP is a server based on the Model Context Protocol (MCP) that allows AI assistants (such as Claude, Cursor, etc.) to interact directly with SQL Server databases. Through natural language, you can explore the database structure, query data, and analyze table relationships without writing complex SQL statements or using specialized database tools.

How to use SQL Server MCP?

It's very simple to use: 1) Add MCP server settings to your AI assistant configuration; 2) Configure database connection information; 3) Restart your AI assistant to start using it. After that, you can directly ask questions in natural language, such as 'Show all databases' or 'Query the latest orders'.

Use cases

It is suitable for scenarios such as database exploration, data analysis, schema review, and data query. It is especially suitable for: 1) Developers to quickly understand the database structure; 2) Data analysts to query data; 3) Project managers to view data statistics; 4) Technical support staff to find specific information.

Main features

Schema exploration

Automatically discover and display the structural information of databases, tables, views, and stored procedures, including detailed information such as column names, data types, and constraints.

Relationship mapping

Intelligently analyze the foreign key relationships between tables to help you understand the data model and the connection methods between tables.

Smart search

Search for table names, column names, views, and stored procedures in the entire database schema to quickly find relevant information.

Safe query

Execute read - only SELECT queries, automatically limit the number of returned rows and query time to prevent impacts on the database.

Cross - platform support

It provides two versions for Windows and macOS. Windows supports native Windows authentication, and macOS supports the Docker environment.

Schema caching

Cache database schema information to improve the response speed of repeated queries. The cache time can be configured.

Advantages

No SQL knowledge required: Operate the database through natural language

Safe and reliable: Read - only mode by default to prevent accidental operations

Quick to get started: Simple configuration, and you can start using it in a few minutes

Intelligent analysis: Automatically discover data relationships and schema information

Cross - platform compatibility: Supports mainstream AI assistants and operating systems

Limitations

Read - only access: Write operations are not supported by default (for security reasons)

Performance limitations: There is a limit on the number of query result rows (default is 1000 rows)

Requires configuration: Database connection needs to be set up for the first use

macOS requires Docker: The macOS version needs to run the SQL Server Docker container

How to use

Select the version suitable for your platform

Select the corresponding version according to your operating system: Windows users use the Windows version (supports Windows authentication), and macOS users use the macOS version (requires Docker).

Configure the AI assistant

Add MCP server settings to your AI assistant configuration file. Here is a configuration example for Claude Desktop:

Set environment variables

Set the corresponding environment variables according to your database configuration. Choose either Windows authentication or SQL Server authentication.

Restart and start using

Restart your AI assistant application, and then you can start querying the database in natural language.

Usage examples

Database exploration

When you need to understand the structure of an unfamiliar database, you can quickly explore all tables and views.

Table structure analysis

When developing or debugging, you need to understand the detailed structure of a specific table.

Data relationship understanding

Analyze the data model and understand the relationships between tables.

Data query

Quickly query data without writing complex SQL statements.

Schema search

Find tables containing specific fields in the entire database.

Frequently Asked Questions

Do I need to install SQL Server?

Is this tool safe? Will it modify my data?

Which AI assistants are supported?

Are there any restrictions on query results?

What are the differences between the macOS version and the Windows version?

How to update to the latest version?

Related resources

Detailed documentation for the Windows version

Complete installation and usage guide for the Windows version

Detailed documentation for the macOS version

Complete installation and usage guide for the macOS version

GitHub repository

Project source code and issue tracking

MCP official documentation

Official documentation for the Model Context Protocol

npm package page

npm package information for the Windows version

🚀 SQL Server MCP - Cross-Platform Database Integration for AI

SQL Server MCP is a solution that enables AI assistants to explore and query SQL Server databases through natural language. It's built as a RAG system optimized for database knowledge exploration, offering various features for database interaction.

✨ Features

🔍 Schema Exploration: List databases, tables, views, and stored procedures.
🔗 Relationship Mapping: Discover foreign key relationships and table dependencies.
🔎 Search & Discovery: Conduct a global schema search across tables, columns, and procedures.
⚡ Safe Query Execution: Execute read - only SELECT queries with automatic timeouts and row limits.
🗄️ Schema Caching: Achieve fast retrieval with configurable TTL (default: 60 minutes).
🔐 Security First: It's read - only by default, with SQL injection prevention and query validation.
🖥️ Cross-Platform: Support native Windows Authentication and macOS Docker.

🎥 Demo

See SQL Server MCP in action with AI assistant integration:

⚠️ Important Note

Watch how natural language queries instantly explore database schemas, find relationships, and retrieve data - all without leaving your AI assistant!

🚀 Quick Start

This repository contains two platform-specific implementations:

Windows Version →

✅ Windows Authentication (ODBC Driver 17)
✅ SQL Server Authentication
✅ Native msnodesqlv8 driver for optimal performance
📖 Windows Setup Guide

macOS Version →

✅ SQL Server Authentication (Docker required)
✅ Pure JavaScript mssql driver (no native dependencies)
📖 macOS Setup Guide

📦 Installation

🎉 Now Available on MCP Registry!

This server is officially published in the Model Context Protocol Registry:

Windows: io.github.TharanaBope/sql-server-mcp
macOS: io.github.TharanaBope/sql-server-mcp-macos

🚀 Quick Start (Recommended)

No installation needed! Just add to your AI assistant's configuration:

Claude Desktop (Windows)

Config Location: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sql-server": {
      "command": "npx",
      "args": ["-y", "@tharanabopearachchi/sql-server-mcp@latest"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "master",
        "SQL_USE_WINDOWS_AUTH": "true"
      }
    }
  }
}

Claude Desktop (macOS)

Config Location: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sql-server": {
      "command": "npx",
      "args": ["-y", "@tharanabopearachchi/sql-server-mcp-macos@latest"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "master",
        "SQL_USE_WINDOWS_AUTH": "false",
        "SQL_USERNAME": "sa",
        "SQL_PASSWORD": "your_password"
      }
    }
  }
}

LM Studio Configuration

Config Location: Varies by platform

Windows: %USERPROFILE%\.lmstudio\config.json
macOS: ~/.lmstudio/config.json

{
  "mcpServers": {
    "sql-server": {
      "command": "npx",
      "args": ["-y", "@tharanabopearachchi/sql-server-mcp@latest"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "master",
        "SQL_USE_WINDOWS_AUTH": "true",
        "SQL_USERNAME": "",
        "SQL_PASSWORD": ""
      }
    }
  }
}

VS Code with Continue Extension

Config Location: ~/.continue/config.json

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@tharanabopearachchi/sql-server-mcp@latest"]
        },
        "env": {
          "SQL_SERVER": "localhost",
          "SQL_DATABASE": "master",
          "SQL_USE_WINDOWS_AUTH": "true"
        }
      }
    ]
  }
}

Cursor IDE

Config Location: Cursor Settings → Features → Model Context Protocol

{
  "mcpServers": {
    "sql-server": {
      "command": "npx",
      "args": ["-y", "@tharanabopearachchi/sql-server-mcp@latest"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "master",
        "SQL_USE_WINDOWS_AUTH": "true"
      }
    }
  }
}

Cline (VS Code Extension)

Config Location: VS Code Settings → Cline → MCP Settings

{
  "mcpServers": {
    "sql-server": {
      "command": "npx",
      "args": ["-y", "@tharanabopearachchi/sql-server-mcp@latest"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "master",
        "SQL_USE_WINDOWS_AUTH": "true"
      }
    }
  }
}

Restart your AI assistant and you're ready to go!

🛠️ Development Setup

For development or local modifications:

Windows

cd sql-server-mcp
npm install
npm run build

👉 Complete Windows Setup Instructions

macOS

cd sql-server-mcp-mac
npm install
npm run build

👉 Complete macOS Setup Instructions

🛠️ Available MCP Tools

The server provides 12 powerful tools for database exploration:

Schema Exploration

list_databases: Discover all available databases.
list_tables: View tables with row counts.
describe_table: Get detailed schema (columns, types, constraints, indexes).
list_views: List all views.
list_stored_procedures: List stored procedures with metadata.
get_procedure_definition: Get full SQL definition.
get_database_overview: High-level statistics.

Relationship Mapping

get_table_relationships: Get foreign key relationships (incoming & outgoing).
get_related_tables: Find directly connected tables.

Search & Discovery

search_schema: Search across tables, columns, views, procedures.
find_column_usage: Find all tables containing a specific column.

Query Execution

execute_query: Execute read-only SELECT queries safely.

💻 Usage Examples

Basic Usage

Once configured, you can ask your AI assistant:

"What databases are available on this server?"

"Show me all tables in the Sales database"

"What's the schema of the Orders table?"

"Find all tables that reference the Customers table"

"Search for any columns related to 'email'"

"Execute: SELECT TOP 10 * FROM Products ORDER BY Price DESC"

⚙️ Configuration

Both versions use environment variables for configuration:

SQL_SERVER=localhost
SQL_DATABASE=master
SQL_PORT=1433
SQL_USE_WINDOWS_AUTH=true          # Windows only
SQL_USERNAME=                       # For SQL Auth
SQL_PASSWORD=                       # For SQL Auth
QUERY_TIMEOUT=30
MAX_RESULT_ROWS=1000
ENABLE_SCHEMA_CACHE=true
CACHE_TTL_MINUTES=60

See platform-specific READMEs for detailed configuration instructions.

🔧 Technical Details

Security Features

✅ Read-only by default: Write operations disabled unless explicitly enabled.
✅ Query validation: Only SELECT statements allowed by default.
✅ Automatic timeouts: Prevents long-running queries.
✅ Row limits: Prevents memory exhaustion.
✅ SQL injection prevention: Query sanitization and validation.
✅ Database whitelisting: Optional restriction to specific databases.

Architecture

MCP/
├── sql-server-mcp/              # Windows implementation
│   ├── src/
│   │   ├── index.ts             # MCP server entry point
│   │   ├── database/            # Connection, caching, queries
│   │   ├── tools/               # 12 MCP tools
│   │   └── types/               # TypeScript interfaces
│   ├── dist/                    # Compiled output
│   ├── package.json
│   └── README.md                # Windows documentation
│
├── sql-server-mcp-mac/          # macOS implementation
│   ├── src/                     # Same structure as Windows
│   └── README.md                # macOS documentation
│
├── LICENSE                      # MIT License
└── README.md                    # This file

🎯 Use Cases

Database Exploration

"What tables exist in this database?"
"Show me the structure of the Users table"
"List all stored procedures"

Schema Research

"Find all tables with an 'email' column"
"Search for anything related to 'invoice'"
"What views are available?"

Relationship Analysis

"How are Orders and Customers related?"
"Show me all tables that reference Products"
"What are the foreign key relationships for this table?"

Data Queries

"Get the top 10 most expensive products"
"Show me recent orders"
"What's the total count of records in each table?"

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

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

🙏 Acknowledgments

Built on Model Context Protocol SDK
Uses mssql and msnodesqlv8 drivers
Inspired by the need for better AI-database integration

📚 Documentation

Windows Setup Guide:
macOS Setup Guide:
Troubleshooting: Check platform-specific TROUBLESHOOTING.md files
MCP Documentation: https://github.com/modelcontextprotocol
Report Issues: https://github.com/TharanaBope/SQL-MCP-Mac-Windows/issues

🌐 Platform-Specific Documentation

Property	Details
Windows	. Key Features: Windows Auth, ODBC Driver, Native performance
macOS	. Key Features: Docker SQL Server, Pure JS, No native deps

Made with ❤️ for the MCP community

⭐ Star this repo if you find it useful! 🐛 Report bugs via Issues 💬 Questions? Check the Discussions

list_databases

List all databases in the SQL Server instance. Used to discover available databases.

Parameters

includeSystem : boolean*

Description

Whether to include system databases (master, tempdb, model, msdb)

list_tables

List all tables and their row counts in a specific database. Crucial for understanding the database structure.

Parameters

database : string*

Description

Database name

describe_table

Get detailed schema information about a table, including columns, data types, constraints, foreign keys, and indexes. Crucial for understanding the table structure.

Parameters

database : string*

Description

Database name

Parameters

tableName : string*

Description

Table name (can include schema, e.g., dbo.Users)

get_table_relationships

Get all foreign key relationships (both incoming and outgoing) of a table. Show how tables are connected.

Parameters

database : string*

Description

Database name

Parameters

tableName : string*

Description

Table name

search_schema

Search for keywords in tables, columns, views, and stored procedures. Ideal for finding where a specific function is implemented.

Parameters

database : string*

Description

Database name

Parameters

searchTerm : string*

Description

Search term or keyword

find_column_usage

Find all tables that contain a column with a specific name. Used to track the usage of a field throughout the database.

Parameters

database : string*

Description

Database name

Parameters

columnName : string*

Description

Exact column name to search for

list_stored_procedures

List all stored procedures in a database.

Parameters

database : string*

Description

Database name

get_procedure_definition

Get the complete SQL definition of a stored procedure.

Parameters

database : string*

Description

Database name

Parameters

procedureName : string*

Description

Stored procedure name

list_views

List all views in a database.

Parameters

database : string*

Description

Database name

get_database_overview

Get high - level statistical information about a database, including the number of tables, views, stored procedures, and schemas.

Parameters

database : string*

Description

Database name

execute_query

Execute a read - only SELECT query on the database. Automatically limited to prevent large result sets. Only SELECT queries are allowed.

Parameters

database : string*

Description

Database name

Parameters

query : string*

Description

SQL SELECT query to execute

get_related_tables

Get all tables that are directly related to a given table through foreign key relationships. Helps understand table dependencies.

Parameters

database : string*

Description

Database name

Parameters

tableName : string*

Description

Table name

Gitlab MCP Server

Certified

The GitLab MCP server is a project based on the Model Context Protocol that provides a comprehensive toolset for interacting with GitLab accounts, including code review, merge request management, CI/CD configuration, and other functions.

TypeScript

21.6K

4.3 points

Duckduckgo MCP Server

Certified

The DuckDuckGo Search MCP Server provides web search and content scraping services for LLMs such as Claude.

Markdownify is a multi-functional file conversion service that supports converting multiple formats such as PDFs, images, audio, and web page content into Markdown format.

A Python-based MCP Server that provides advanced to-do list management and content organization functions through the Notion API, enabling seamless integration between AI models and Notion.

Framelink Figma MCP Server is a server that provides access to Figma design data for AI programming tools (such as Cursor). By simplifying the Figma API response, it helps AI more accurately achieve one - click conversion from design to code.

UnityMCP is a Unity editor plugin that implements the Model Context Protocol (MCP), providing seamless integration between Unity and AI assistants, including real - time state monitoring, remote command execution, and log functions.

26.9K

5 points

Gmail MCP Server

A Gmail automatic authentication MCP server designed for Claude Desktop, supporting Gmail management through natural language interaction, including complete functions such as sending emails, label management, and batch operations.

Context7 MCP is a service that provides real-time, version-specific documentation and code examples for AI programming assistants. It is directly integrated into prompts through the Model Context Protocol to solve the problem of LLMs using outdated information.

TypeScript

84.9K

4.7 points

Zhiqi Future, Your AI Solution Think Tank

English 简体中文繁體中文にほんご

Sql MCP Mac Windows

Overview

Installation

Tools List

Content Details

Alternatives

What is SQL Server MCP?

How to use SQL Server MCP?

Use cases

Main features

How to use

Usage examples

Frequently Asked Questions

Related resources

Installation

🚀 SQL Server MCP - Cross-Platform Database Integration for AI

✨ Features

🎥 Demo

🚀 Quick Start

Windows Version →

macOS Version →

📦 Installation

🎉 Now Available on MCP Registry!

🚀 Quick Start (Recommended)

Claude Desktop (Windows)

Claude Desktop (macOS)

🛠️ Development Setup

Windows

macOS

🛠️ Available MCP Tools

Schema Exploration

Relationship Mapping

Search & Discovery

Query Execution

💻 Usage Examples

Basic Usage

⚙️ Configuration

🔧 Technical Details

Security Features

Architecture

🎯 Use Cases

Database Exploration

Schema Research

Relationship Analysis

Data Queries

🤝 Contributing

📄 License

🙏 Acknowledgments

📚 Documentation

🌐 Platform-Specific Documentation

Alternatives