MCP-Go-MSSQL

A secure Go-based solution for Microsoft SQL Server connectivity supporting both Claude Desktop (via MCP server) and Claude Code (via CLI tools).

🤖 Designed for AI Assistants

This server is optimized for use with Claude Desktop and AI assistants, providing:

✅ Safe production access - AI can analyze without risk of data corruption
✅ Full query capabilities - AI can perform complex SELECT queries, JOINs, CTEs
✅ Temporal workspace - Optional whitelist for AI to use temporary tables
✅ Smart restrictions - Blocks dangerous operations while keeping AI fully functional

👉 See AI Usage Guide for detailed examples of what Claude can and cannot do.

Features

Security-first design with configurable TLS encryption for database connections
Granular table permissions with whitelist for AI-safe database access
SQL injection protection using prepared statements exclusively
Multi-table query validation preventing unauthorized access via JOINs/subqueries
Connection timeouts and resource limits with pooling
Flexible connection support for modern and legacy SQL Server versions
Custom connection strings for special configurations (SQL Server 2008+)
Configurable security parameters for production and development environments
Secure logging with automatic sensitive data sanitization

Quick Start

1. Setup Dependencies

go mod tidy

2. Configure Database Connection

Option A: Environment Variables (Recommended)

# Copy the example environment file
cp .env.example .env

# Edit .env with your database credentials
# Then load the environment variables:
source .env  # Linux/Mac
# or for Windows PowerShell:
# Get-Content .env | ForEach-Object { $name, $value = $_ -split '=', 2; [Environment]::SetEnvironmentVariable($name, $value) }

Option B: Direct Export (Linux/Mac)

export MSSQL_SERVER="your-server.database.windows.net"
export MSSQL_DATABASE="YourDatabase"
export MSSQL_USER="your_user"
export MSSQL_PASSWORD="your_password"
export DEVELOPER_MODE="false"

Option C: Claude Desktop Integration

# Use config.example.json as template for Claude Desktop
cp config.example.json config.json
# Edit config.json with your database credentials

Build and Run

# Quick build (Windows)
build.bat

# Manual build
go build -o mcp-go-mssql.exe

# Development mode (detailed errors)
go run main.go

# Production build (optimized)
go build -ldflags "-w -s" -o mcp-go-mssql-secure.exe

Configuration

Claude Desktop Configuration Examples

AI-Safe Production Configuration (RECOMMENDED for AI Assistants):

{
  "mcpServers": {
    "production-db-ai-safe": {
      "command": "C:\\path\\to\\mcp-go-mssql.exe",
      "args": [],
      "env": {
        "MSSQL_SERVER": "your-server.database.windows.net",
        "MSSQL_DATABASE": "YourDatabase",
        "MSSQL_USER": "ai_user",
        "MSSQL_PASSWORD": "secure_password",
        "MSSQL_PORT": "1433",
        "MSSQL_READ_ONLY": "true",
        "MSSQL_WHITELIST_TABLES": "temp_ai,v_temp_ia",
        "DEVELOPER_MODE": "false"
      }
    }
  }
}

Standard Production Configuration:

{
  "mcpServers": {
    "production-db": {
      "command": "C:\\path\\to\\mcp-go-mssql.exe",
      "args": [],
      "env": {
        "MSSQL_SERVER": "your-server.database.windows.net",
        "MSSQL_DATABASE": "YourDatabase",
          "MSSQL_AUTH": "sql",
          "MSSQL_USER": "user",
          "MSSQL_PASSWORD": "password",
        "MSSQL_PORT": "1433",
        "DEVELOPER_MODE": "false"
      }
    }
  }
}

Windows Integrated Authentication (SSPI - Named Pipes):

Option 1: Access a specific database:

{
  "mcpServers": {
    "production-db-windows-auth": {
      "command": "C:\\path\\to\\mcp-go-mssql.exe",
      "args": [],
      "env": {
        "MSSQL_SERVER": ".",
        "MSSQL_DATABASE": "YourDatabase",
        "MSSQL_AUTH": "integrated",
        "DEVELOPER_MODE": "false"
      }
    }
  }
}

Option 2: Access all databases (no database specified):

{
  "mcpServers": {
    "production-db-windows-auth-all": {
      "command": "C:\\path\\to\\mcp-go-mssql.exe",
      "args": [],
      "env": {
        "MSSQL_SERVER": ".",
        "MSSQL_AUTH": "integrated",
        "DEVELOPER_MODE": "false"
      }
    }
  }
}

ℹ️ Windows Auth Note: Uses current Windows user credentials automatically (no passwords needed). MSSQL_SERVER="." for local server, "localhost", or server hostname for remote servers. MSSQL_DATABASE is optional - if omitted, connects to user's default database. Works with Active Directory and local Windows accounts. See Windows Authentication Guide for detailed setup and troubleshooting.

Legacy SQL Server (Custom Connection String):

{
  "mcpServers": {
    "legacy-db": {
      "command": "C:\\path\\to\\mcp-go-mssql.exe",
      "args": [],
      "env": {
        "MSSQL_CONNECTION_STRING": "sqlserver://sa:YourPassword@legacy-server:1433?database=LegacyDB&encrypt=disable&trustservercertificate=true",
        "DEVELOPER_MODE": "true"
      }
    }
  }
}

Environment Variables

All database connections use environment variables for security. See .env.example for complete configuration examples.

Required Variables (when not using custom connection string):

MSSQL_SERVER: SQL Server hostname or IP address
MSSQL_AUTH: Authentication mode (sql, integrated/windows, or azure)

For SQL Server Authentication (MSSQL_AUTH=sql or not set):

MSSQL_DATABASE: Database name to connect to (required)
MSSQL_USER: Username for SQL Server authentication (required)
MSSQL_PASSWORD: Password for SQL Server authentication (required)

For Windows Integrated Authentication (MSSQL_AUTH=integrated or windows):

MSSQL_DATABASE: Database name (optional - if omitted, connects to default database for the Windows user)
No MSSQL_USER or MSSQL_PASSWORD needed - uses Windows credentials automatically

Optional Variables:

MSSQL_PORT: SQL Server port (default: 1433)
MSSQL_ENCRYPT: Override encryption setting ("true" or "false")
MSSQL_CONNECTION_STRING: Complete custom connection string (overrides all other MSSQL_* settings)
MSSQL_AUTH: Authentication mode for connecting to SQL Server. Supported values:
- sql (default) - SQL Server authentication using MSSQL_USER and MSSQL_PASSWORD. Requires MSSQL_DATABASE.
- integrated or windows - Windows Integrated Authentication (SSPI). Only supported on Windows; the process runs under the current Windows user's credentials and must have proper DB permissions. MSSQL_DATABASE is optional - if omitted, connects to the user's default database. Key benefits: No passwords in config files, uses Active Directory/Windows security, seamless single sign-on.
- azure - Azure Active Directory authentication (advanced; may require additional config and is not fully implemented by default).
MSSQL_READ_ONLY: Security restriction ("true" allows only SELECT queries, "false" allows all operations)
MSSQL_AUTOPILOT: Autonomous AI mode (default: "false"). "true" skips schema validation — AI can query tables that don't exist yet without interruption. Complements READ_ONLY: when both are enabled, modifications are restricted to whitelist tables while allowing flexible development without schema interruptions. Does NOT skip whitelist protection or destructive operation confirmation.
- Example: READ_ONLY=true + AUTOPILOT=true + WHITELIST_TABLES=temp_ai → AI can modify temp_ai and query non-existent tables freely, but cannot touch other tables
MSSQL_WHITELIST_TABLES: Granular permissions (comma-separated list of tables/views allowed for modification when MSSQL_READ_ONLY=true)
- Example: "temp_ai,v_temp_ia"
- Enables AI to modify specific tables while protecting production data
- Validates ALL tables in queries (including JOINs, subqueries, CTEs)
- See WHITELIST_SECURITY.md for details
DEVELOPER_MODE:
- "true": Development mode (detailed errors, allows self-signed certificates, disables encryption by default)
- "false": Production mode (generic errors, strict certificate validation, forces encryption)

🔧 Custom Connection String Priority: When MSSQL_CONNECTION_STRING is set, all other MSSQL_* variables are ignored except DEVELOPER_MODE.

Environment Setup Examples:

# Azure SQL Database (Production)
MSSQL_SERVER=your-server.database.windows.net
MSSQL_DATABASE=YourAzureDB
MSSQL_USER=your_user@your-server
MSSQL_PASSWORD=your_secure_password
DEVELOPER_MODE=false

# Local Development (No Encryption)
MSSQL_SERVER=localhost
MSSQL_DATABASE=DevDB
MSSQL_USER=dev_user
MSSQL_PASSWORD=dev_password
DEVELOPER_MODE=true

# Local Development (Force Encryption)
MSSQL_SERVER=localhost
MSSQL_DATABASE=DevDB
MSSQL_USER=dev_user
MSSQL_PASSWORD=dev_password
MSSQL_ENCRYPT=true
DEVELOPER_MODE=true

# Legacy SQL Server (e.g., SQL Server 2008) - Custom Connection String
MSSQL_CONNECTION_STRING=sqlserver://sa:YourPassword@legacy-server:1433?database=LegacyDB&encrypt=disable&trustservercertificate=true
DEVELOPER_MODE=true

# Read-Only Mode (Security Restricted)
MSSQL_SERVER=server.example.com
MSSQL_DATABASE=MyDatabase
MSSQL_USER=readonly_user
MSSQL_PASSWORD=readonly_password
MSSQL_READ_ONLY=true
MSSQL_MAX_QUERY_SIZE=2097152
DEVELOPER_MODE=false

# Windows Integrated Authentication (SSPI) - runs under the current Windows user
# Example 1: Connect to specific database
MSSQL_AUTH=integrated
MSSQL_SERVER=localhost
MSSQL_DATABASE=YourDatabase
DEVELOPER_MODE=false

# Example 2: Connect to default database (database name optional)
MSSQL_AUTH=integrated
MSSQL_SERVER=.
DEVELOPER_MODE=true

# Example 3: Remote server with domain authentication
MSSQL_AUTH=integrated
MSSQL_SERVER=SQL-SERVER.company.local
MSSQL_DATABASE=ProductionDB
DEVELOPER_MODE=false

# AI-Safe Mode with Whitelist (RECOMMENDED for AI Assistants)
MSSQL_SERVER=prod-server.database.windows.net
MSSQL_DATABASE=ProductionDB
MSSQL_USER=ai_user
MSSQL_PASSWORD=secure_password
MSSQL_READ_ONLY=true
MSSQL_WHITELIST_TABLES=temp_ai,v_temp_ia
DEVELOPER_MODE=false

# Dynamic Multi-Database Mode (single server, multiple connections)
MSSQL_SERVER=localhost
MSSQL_DATABASE=DevDB
MSSQL_USER=dev_user
MSSQL_PASSWORD=dev_password
DEVELOPER_MODE=true
MSSQL_DYNAMIC_MODE=true
MSSQL_DYNAMIC_MAX_CONNECTIONS=10
# Use tools: dynamic_connect, dynamic_list, dynamic_disconnect
# In query_database, use parameter: connection=<alias>

Dynamic Multi-Connection Mode

When MSSQL_DYNAMIC_MODE=true is enabled, the server can connect to multiple databases from a single MCP instance. Connections are pre-configured in .env with credentials, and the AI only sees safe aliases — no sensitive data exposed.

Available Tools:

dynamic_connect - Activate a pre-configured connection by alias
dynamic_list - List all available dynamic connections (shows alias, server, database — NO passwords)
dynamic_disconnect - Close a named dynamic connection

How it works:

Connections are defined in .env with prefix MSSQL_DYNAMIC_<ALIAS>_
AI calls dynamic_connect with just an alias (no credentials in params)
Server reads credentials from environment variables
AI sees only server/database names, not passwords or users

Example .env configuration:

# Default connection (always available)
MSSQL_SERVER=10.203.3.10
MSSQL_DATABASE=JJP_CRM
MSSQL_USER=sa
MSSQL_PASSWORD=secret123

# Dynamic connections (AI sees only: identity, ferratge, crm)
MSSQL_DYNAMIC_IDENTITY_SERVER=10.203.3.11
MSSQL_DYNAMIC_IDENTITY_DATABASE=JJP_CRM_IDENTITY
MSSQL_DYNAMIC_IDENTITY_USER=ppp
MSSQL_DYNAMIC_IDENTITY_PASSWORD=ppppp

MSSQL_DYNAMIC_FERRATGE_SERVER=10.203.3.12
MSSQL_DYNAMIC_FERRATGE_DATABASE=JJP_Ferratge_PROD
MSSQL_DYNAMIC_FERRATGE_USER=ferratge_user
MSSQL_DYNAMIC_FERRATGE_PASSWORD=otra_password

Usage:

// 1. List available connections (AI sees alias, server, database only)
tool: dynamic_list

// 2. Activate a connection by alias (no credentials exposed)
tool: dynamic_connect
params: {"alias": "identity"}

// 3. Query using the connection
tool: query_database
params: {"sql": "SELECT TOP 10 * FROM customers", "connection": "identity"}

// 4. Disconnect when done
tool: dynamic_disconnect
params: {"alias": "identity"}

Claude Desktop Configuration for Dynamic Mode:

{
  "mcpServers": {
    "mssql-multi": {
      "command": "C:\\MCPs\\clone\\mcp-go-mssql\\build\\mcp-go-mssql.exe",
      "args": [],
      "env": {
        "DEVELOPER_MODE": "true",
        "MSSQL_DYNAMIC_MODE": "true",
        "MSSQL_DYNAMIC_MAX_CONNECTIONS": "10"
      }
    }
  }
}

Note: All credentials are stored in .env, NOT in Claude Desktop config. The MCP server env only needs MSSQL_DYNAMIC_MODE=true — no database credentials in the JSON config.

Security Features

Database Access Control

Granular table permissions with whitelist system:
- Validate ALL tables in queries (FROM, JOIN, subqueries, CTEs)
- Block unauthorized access even through complex SQL patterns
- Perfect for AI assistants accessing production databases
- Example: DELETE temp_ai FROM temp_ai JOIN users → BLOCKED if users not whitelisted
- See WHITELIST_SECURITY.md for complete guide
Read-only mode for query-only access
Prepared statements to prevent SQL injection
Input validation and sanitization

Connection Security

Configurable TLS encryption for database connections:
- Production: Forces encryption (encrypt=true)
- Development: Allows disabling encryption for local SQL Server instances
Flexible certificate validation:
- Production: Strict certificate validation (trustservercertificate=false)
- Development: Allows self-signed certificates (trustservercertificate=true)
Connection pooling with resource limits
Secure error handling with production/development modes

Requirements

Go 1.26+
Microsoft SQL Server with TLS support
Network access to SQL Server (port 1433)

Troubleshooting

Connection Issues

TLS Certificate Issues:

Error: "certificate signed by unknown authority"
Solution: Set DEVELOPER_MODE=true for self-signed certificates

Encryption Issues:

Error: "SSL Provider: No credentials are available in the security package"
Solution: Set DEVELOPER_MODE=true to disable encryption for local SQL Server

Force No Encryption (Development):

# For local SQL Server without TLS
DEVELOPER_MODE=true
# This automatically sets encrypt=false for development

TLS Handshake Issues (Legacy SQL Server):

Error: "TLS Handshake failed: tls: server selected unsupported protocol version"
Solution: Use custom connection string with URL format for SQL Server 2008/2012

Connection String Formats:

Standard Format (Modern SQL Server 2014+):

# Automatically used when individual variables are set
MSSQL_SERVER=server.example.com
MSSQL_DATABASE=MyDatabase
MSSQL_USER=username
MSSQL_PASSWORD=password
DEVELOPER_MODE=true

URL Format (Legacy SQL Server 2008-2012):

# Use this for older SQL Server versions
MSSQL_CONNECTION_STRING=sqlserver://username:password@server:1433?database=dbname&encrypt=disable&trustservercertificate=true
DEVELOPER_MODE=true

No Encryption (Development):

# For local SQL Server without TLS
DEVELOPER_MODE=true
# This automatically sets encrypt=false for development

Connection Test

# Make sure environment variables are set first
cd test
go run test-connection.go

# For debugging connection issues
cd debug
go run debug-connection.go

Security Notes

⚠️ Never commit .env or config.json files with real credentials
✅ Always use environment variables for sensitive data
🔒 Use strong passwords and enable TLS encryption
🏢 For production: Set DEVELOPER_MODE=false and use valid certificates

Usage Options

🖥️ Claude Desktop (MCP Server)

Use main.go as an MCP server with Claude Desktop:

Available Tools:

Tool	Description
`get_database_info`	Check connection status, encryption, and access mode
`query_database`	Execute SQL queries securely (prepared statements)
`list_tables`	List all tables and views in the database
`describe_table`	Get column structure (supports `schema.table` format)
`list_databases`	List all user databases on the server
`get_indexes`	Get indexes for a specific table
`get_foreign_keys`	Get FK relationships (incoming and outgoing)
`list_stored_procedures`	List all stored procedures
`execute_procedure`	Execute whitelisted stored procedures

Environment Variables for New Features:

# Whitelist stored procedures for execute_procedure tool
MSSQL_WHITELIST_PROCEDURES="sp_GetCustomerOrders,sp_GenerateReport"

💻 Claude Code (CLI Tool)

Use claude-code/db-connector.go directly with Claude Code:

cd claude-code
go run db-connector.go test                    # Test connection
go run db-connector.go tables                  # List tables
go run db-connector.go query "SELECT ..."      # Execute queries

See claude-code/README.md for detailed Claude Code integration.

📚 Documentation

For Users

AI Usage Guide - How Claude/AI works with security restrictions
Windows Authentication Guide - Setup and troubleshooting for Windows Integrated Auth (SSPI)
Whitelist Security - Configure granular table permissions
README (this file) - Installation and configuration

For Security Audits

Security Analysis - Comprehensive security assessment
Security Audit Report - Detailed audit findings

For Developers

Claude Code Documentation - Using with Claude Code
Test Results - Test coverage and results

Project Structure

mcp-go-mssql/
├── main.go                          # MCP server for Claude Desktop
├── build.bat                        # Windows build script
├── docs/                            # Documentation
│   ├── AI_USAGE_GUIDE.md           # How to use with Claude/AI ⭐
│   ├── SECURITY_ANALYSIS.md        # Security assessment
│   ├── SECURITY_AUDIT_REPORT.md    # Audit report
│   ├── SECURITY_SUMMARY.md         # Security summary
│   ├── UPDATE_GO.md                # Go version upgrade guide
│   ├── WHITELIST_SECURITY.md       # Table whitelist guide
│   └── ...                         # Other documentation
├── scripts/                         # Utility scripts
│   ├── security-check.ps1          # Automated security validation
│   ├── test-mcp-server.ps1         # Server testing
│   └── ...                         # Other scripts
├── test/                            # Tests
│   ├── security/                   # Security test suite
│   │   ├── cves_test.go           # CVE checks
│   │   └── security_tests.go       # Security validation
│   └── test-connection.go          # Connection testing
├── claude-code/                     # Claude Code integration
│   ├── db-connector.go             # CLI database tool
│   └── README.md                   # Claude Code documentation
├── .env.example                    # Environment variables template
├── config.example.json             # Claude Desktop config template
├── CLAUDE.md                       # Claude Code project documentation
└── README.md                       # This file

License

This project is designed for secure database connectivity in critical environments.

Name		Name	Last commit message	Last commit date
Latest commit History 89 Commits
.claude/skills/mcp-mssql-tools		.claude/skills/mcp-mssql-tools
.github		.github
cli		cli
cmd/dashboard		cmd/dashboard
config		config
debug		debug
internal		internal
scripts		scripts
test		test
website		website
.env.example		.env.example
.env.test.example		.env.test.example
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.mcp.json		.mcp.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
build.bat		build.bat
build.sh		build.sh
config.example.json		config.example.json
config.go		config.go
go.mod		go.mod
go.sum		go.sum
main.go		main.go
main_fuzz_test.go		main_fuzz_test.go
main_mcp_spec_test.go		main_mcp_spec_test.go
main_permissions_test.go		main_permissions_test.go
main_ratelimit_test.go		main_ratelimit_test.go
main_test.go		main_test.go
mcp_protocol.go		mcp_protocol.go
security_logger.go		security_logger.go
similarity.go		similarity.go
tools_confirm.go		tools_confirm.go
tools_database.go		tools_database.go
tools_dynamic.go		tools_dynamic.go
tools_procedure.go		tools_procedure.go

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

MCP-Go-MSSQL

🤖 Designed for AI Assistants

Features

Quick Start

1. Setup Dependencies

2. Configure Database Connection

Configuration

Claude Desktop Configuration Examples

Environment Variables

Dynamic Multi-Connection Mode

Security Features

Database Access Control

Connection Security

Requirements

Troubleshooting

Connection Issues

Connection Test

Security Notes

Usage Options

🖥️ Claude Desktop (MCP Server)

💻 Claude Code (CLI Tool)

📚 Documentation

For Users

For Security Audits

For Developers

Project Structure

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages