SQL Server MCP
An MCP (Model Context Protocol) server that connects AI assistants to Microsoft SQL Server databases. Enables AI tools like GitHub Copilot, Cursor, Cline, Claude Desktop, and Claude Code to explore database schemas and execute read-only queries safely.
Features
- 29 built-in tools for comprehensive database analysis and management
- Read-only by design — uses
db_datareaderrole, blocks all destructive SQL - SQL injection protection — AST-based query validation + keyword blocklist
- Automatic row limits — prevents memory overflow with smart
TOP Ninjection - AI-friendly errors — structured error responses with actionable suggestions
- Schema caching — 1-hour TTL metadata cache reduces redundant DB calls
- Unicode/Vietnamese support — full NVARCHAR UTF-8 passthrough
- Dual transport —
stdio(default) for local AI tools,HTTP/SSEfor web clients - Data analysis — table statistics, index information, and column distribution
- Data export — export table data to JSON or CSV format
- Complete schema understanding — views, constraints, stored procedures, and server info
- Security auditing — user management and permission analysis
- Enhanced profiling — detailed column distribution with pattern recognition
- Dependency mapping — full dependency analysis for tables and columns
- Schema management — comprehensive schema organization and analysis
- Data quality validation — integrity checks and comprehensive profiling
- Documentation automation — generate schema documentation and ER diagrams
Available Tools
Database & Schema (3 tools)
Schema Exploration (5 tools)
Data Analysis (6 tools)
Dependencies & Usage (2 tools)
Data Quality (2 tools)
Documentation (3 tools)
Migration & Comparison (2 tools)
Server & System (1 tool)
Security & Users (2 tools)
Data Export & Query (3 tools)
Quick Start
1. Install
git clone https://github.com/az-coder-123/sql-server-mcp.git
cd sql-server-mcp
npm install
npm run build
2. Configure
Copy the environment template and fill in your SQL Server credentials:
cp .env.example .env
Edit .env:
DB_HOST=localhost
DB_PORT=1433
DB_NAME=MyDatabase
DB_USER=readonly_user
DB_PASSWORD=your_password
DB_ENCRYPT=true
DB_TRUST_SERVER_CERT=false
Important: The
DB_USERshould have thedb_datareaderrole only. The server blocks all write operations at the code level, but defense-in-depth at the database level is strongly recommended.
3. Run
# stdio mode (default — for AI tools)
npm start
# Development mode (with hot reload)
npm run dev
# HTTP/SSE mode (for web clients)
MCP_TRANSPORT=http npm start
Integration with AI Tools
GitHub Copilot (VS Code)
Create .vscode/mcp.json in your project:
{
"servers": {
"sql-server-mcp": {
"type": "stdio",
"command": "node",
"args": ["/path/to/sql-server-mcp/dist/index.js"],
"env": {
"DB_SERVER": "localhost",
"DB_DATABASE": "MyDatabase",
"DB_USER": "readonly_user",
"DB_PASSWORD": "${input:dbPassword}"
}
}
}
}
VS Code will securely prompt for the password at runtime via
${input:dbPassword}.
Cursor
Create .cursor/mcp.json:
{
"mcpServers": {
"sql-server-mcp": {
"command": "node",
"args": ["/path/to/sql-server-mcp/dist/index.js"],
"env": {
"DB_SERVER": "localhost",
"DB_DATABASE": "MyDatabase",
"DB_USER": "readonly_user",
"DB_PASSWORD": "your_password"
}
}
}
}
Cline (VS Code Extension)
- Open Cline settings in VS Code
- Go to MCP Servers → Add Server
- Select Command (stdio)
- Enter:
- Command:
node - Args:
/path/to/sql-server-mcp/dist/index.js - Env:
DB_SERVER=localhost,DB_DATABASE=MyDatabase,DB_USER=readonly_user,DB_PASSWORD=your_password
- Command:
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %AppData%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"sql-server-mcp": {
"command": "node",
"args": ["/path/to/sql-server-mcp/dist/index.js"],
"env": {
"DB_SERVER": "localhost",
"DB_DATABASE": "MyDatabase",
"DB_USER": "readonly_user",
"DB_PASSWORD": "your_password"
}
}
}
}
Claude Code (CLI)
claude --mcp-config ./mcp-config.json "Show me all tables in database"
Where mcp-config.json uses the same mcpServers format as Claude Desktop above.
Configuration Reference
All settings are configured via environment variables (or .env file):
Security
This server is designed for read-only database access with multiple layers of protection:
- Database-level: Uses a
db_datareader-only account withreadOnlyIntentconnection flag - Query validation: AST-based parsing via
node-sql-parser(with regex fallback for T-SQL edge cases) - Keyword blocklist:
INSERT,UPDATE,DELETE,DROP,EXEC,TRUNCATE,ALTER,CREATE,GRANT,REVOKE,MERGEand more - Multi-statement blocking: Semicolons outside string literals are rejected
- Row limiting: Automatic
TOP Ninjection prevents memory exhaustion - Payload truncation: Responses exceeding 1MB are truncated with a warning
- Connection timeout: 30-second hard timeout on all queries
Project Structure
sql-server-mcp/
├── src/
│ ├── index.ts # Server entry point, tool registration, transport
│ ├── config/database.ts # Connection pool, env vars
│ ├── tools/
│ │ ├── schemaTools.ts # list_databases, list_tables, describe_table, relationships, search
│ │ ├── schemaManagementTools.ts # list_schemas
│ │ ├── queryTools.ts # execute_read_query
│ │ ├── tableStatisticsTools.ts # get_table_statistics
│ │ ├── tableIndexTools.ts # get_table_indexes
│ │ ├── tableAnalysisTools.ts # analyze_table
│ │ ├── columnTools.ts # get_column_distribution
│ │ ├── storedProcedureTools.ts # list_stored_procedures
│ │ ├── exportTools.ts # export_table_data
│ │ ├── viewTools.ts # get_view_definition
│ │ ├── constraintTools.ts # list_constraints
│ │ ├── serverInfoTools.ts # get_server_info
│ │ ├── procedureDefinitionTools.ts # get_procedure_definition
│ │ ├── userTools.ts # list_users, get_user_permissions
│ │ ├── dependencyTools.ts # get_table_dependencies
│ │ ├── usageTools.ts # get_column_usage
│ │ ├── dataIntegrityTools.ts # validate_data_integrity
│ │ ├── dataProfileTools.ts # get_data_profile
│ │ ├── documentationTools.ts # generate_schema_documentation
│ │ ├── apiDocumentationTools.ts # generate_api_documentation
│ │ ├── migrationTools.ts # create_migration_scripts
│ │ ├── schemaComparisonTools.ts # compare_schemas
│ │ └── diagramTools.ts # create_entity_relationship_diagram
│ ├── types/index.ts # Shared TypeScript interfaces
│ ├── utils/
│ │ ├── sqlValidator.ts # AST + regex query validation, TOP injection
│ │ └── errorMapper.ts # SQL error code → AI-friendly messages
│ └── cache/schemaCache.ts # In-memory TTL cache
├── tests/ # Unit tests (vitest)
├── dist/ # Compiled output (npm run build)
├── .env.example # Environment variable template
└── package.json
Development
# Install dependencies
npm install
# Run in dev mode (hot reload)
npm run dev
# Run tests
npm test
# Build for production
npm run build
License
ISC