@gishubperu/mcp-mssql

Enterprise-grade SQL Server (MSSQL) MCP Server for AI Agents. Provides a secure, robust, and highly configurable bridge between Large Language Models (like Claude, GPT-4, etc.) and your SQL Server databases.

🚀 Features

• Read-Only by Default: Ensures AI agents can't modify data unless explicitly permitted.
• Semantic Security: Uses AST parsing to block access to system tables (sys.*, INFORMATION_SCHEMA).
• Deep Protection: Multi-layered blocklist for xp_cmdshell, timing attacks, and distributed queries.
• Dynamic Permissions: Enable DML/DDL/DCL at runtime via specialized tools.
• Multi-Profile Support: Switch between multiple environments (Dev, Test, Prod) without restarting.
• Zero-Config Flow: Start instantly with a simple .ghp/mssql.json file.
• Dual Transport: Supports standard stdio and local HTTP sessions.

🛠 Installation

# Direct run via npx
npx @gishubperu/mcp-mssql

# Or install globally
npm install -g @gishubperu/mcp-mssql

💻 Usage with Claude Desktop

Add this entry to your claude_desktop_config.json:

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "@gishubperu/mcp-mssql"]
    }
  }
}

The server will automatically look for .ghp/mssql.json in your current workspace root.

⚙️ Configuration

Option 1: Configuration File (Recommended)

Create a file named .ghp/mssql.json in your project root or ~/.ghp/mssql.json for global access.

Simple Format:

{
  "url": "mssql://user:password@localhost:1433/MyDatabase",
  "permissions": { "dml": true, "ddl": false }
}

Multi-Profile Format:

{
  "profiles": {
    "dev": { "url": "mssql://dev:pass@localhost:1433/app_dev", "permissions": { "dml": true } },
    "prod": { "url": "mssql://reader:pass@prod-server:1433/app_prod", "permissions": { "dml": false } }
  },
  "default": "dev"
}

Option 2: Environment Variables

| Variable | Default | Description | | --- | --- | --- | | DATABASE_URL | — | SQL Server connection string (e.g., mssql://user:pass@host:1433/db) | | MCP_TRANSPORT | stdio | stdio (for AI clients) or http | | MCP_HTTP_PORT | 3000 | Port for HTTP transport | | PROFILE | — | Initial profile name to load | | DEBUG | false | Log all SQL statements to stderr |

🛠 Tools Provided

| Tool | Parameters | Description | | --- | --- | --- | | query | sql, params | Runs a read-only SELECT query. Blocked if write is detected. | | list_tables | schema | Lists all tables, types and estimated row counts (default: dbo). | | describe_table | table, schema | Shows columns, data types, indexes and constraints. | | execute_dml | sql, params | Runs INSERT/UPDATE/DELETE. Requires dml permission. | | execute_ddl | sql | Runs CREATE/ALTER/DROP. Requires ddl permission. | | execute_dcl | sql | Runs GRANT/REVOKE. Requires dcl permission. | | configure_permissions | dml, ddl, dcl | Toggle permissions for the current session. | | set_profile | name | Switch to a different database profile on-the-fly. | | get_current_profile | — | Returns host, database and active permissions. | | list_profiles | — | Lists all available profile names defined in config. |

🔒 Security Policy

1. Semantic Validation

Unlike simple regex servers, this server parses the SQL into an Abstract Syntax Tree (AST). It identifies the target tables and schemas before execution.

• Forbidden: Any access to sys.*, msdb.*, master.*, model.* or INFORMATION_SCHEMA.

2. Injection Blocklist

Protects against advanced T-SQL injection vectors:

• Stored Procedures: Blocks xp_cmdshell, xp_regread, sp_configure.
• Distributed Queries: Blocks OPENROWSET, OPENDATASOURCE, OPENQUERY.
• Timing Attacks: Blocks WAITFOR DELAY and pg_sleep (parity).
• Parity: Also blocks Oracle and PostgreSQL specific dangerous patterns to prevent cross-dialect attacks.

⚠️ Troubleshooting

1. Connection Timeout: Ensure TCP/IP is enabled in SQL Server Configuration Manager. By default, SQL Server Express only enables Shared Memory.
2. Authentication: If using Windows Authentication, ensure the connection string is correctly formatted or use SQL Login for easier setup in MCP.
3. Port 1433: Ensure the port is open in your firewall and the SQL Browser service is running if using named instances.

© 2026 GisHub Perú SAC. MIT License. Made with ❤️ in Perú.