MCP SQL Server

MCP server written in Go for connecting LLM tools to Microsoft SQL Server over stdio.

Features

• Read-only queries with sql_select.
• Write statements with sql_execute for INSERT, UPDATE, DELETE, and MERGE.
• Optional schema changes with CREATE, ALTER, DROP, and TRUNCATE.
• Database discovery: databases, schemas, tables, views.
• Table schema inspection: columns, primary keys, foreign keys, indexes, triggers.
• Stored procedure discovery, definition lookup, and execution.
• Trigger and object definition lookup.
• RAG Knowledge Base: Persistent schema memory using SQLite (no external dependencies).
• Auto-learn: Automatically learns schema on describe_table calls.
• Semantic search: Query learned schema with rag_query.
• Designed for stdio MCP clients such as Codex, IDE extensions, and other LLM tools.

Configuration

Environment variables:

Variable	Default	Description
SQL_SERVER_CONNECTION_STRING	empty	Full sqlserver connection string. Overrides host/user settings.
SQL_SERVER_HOST	localhost	SQL Server host.
SQL_SERVER_PORT	1433	SQL Server port.
SQL_SERVER_USER	sa	SQL Server login.
SQL_SERVER_PASSWORD	empty	SQL Server password.
SQL_SERVER_DATABASE	master	Initial database.
SQL_SERVER_ENCRYPT	disable	Driver encryption mode.
SQL_SERVER_TRUST_CERT	true	Trust server certificate.
SQL_SERVER_CONNECT_TIMEOUT	10s	Connection timeout.
SQL_SERVER_QUERY_TIMEOUT	60s	Reserved for future per-query timeout handling.
SQL_SERVER_MAX_OPEN_CONNS	10	Max open DB connections.
SQL_SERVER_MAX_IDLE_CONNS	5	Max idle DB connections.
MCP_SQLSERVER_MAX_ROWS	500	Maximum rows returned by sql_select.
MCP_SQLSERVER_ALLOW_SCHEMA_CHANGES	false	Allow CREATE, ALTER, DROP, TRUNCATE.
MCP_SQLSERVER_ALLOW_DANGEROUS_SQL	false	Allow blocked capabilities such as xp_cmdshell.
MCP_SQLSERVER_ALLOW_PROCEDURE_CALLS	true	Allow stored procedure execution.
MCP_RAG_ENABLED	true	Enable RAG knowledge base.
MCP_RAG_AUTO_LEARN	true	Auto-learn schema on describe_table.

Quick Install

Windows

Run these commands in PowerShell:

git clone https://github.com/TranHuyThang9999/mcp-sqlserver.git
cd mcp-sqlserver
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

This downloads the latest Windows release package and starts the installer.

The installer asks for:

• SQL Server host
• SQL Server port
• SQL Server username
• SQL Server password
• MCP client to configure

Linux/macOS

git clone https://github.com/TranHuyThang9999/mcp-sqlserver.git
cd mcp-sqlserver
./scripts/install.sh

Manual Download

You can also download a package from the GitHub Releases page:

• Windows: mcp-sqlserver-windows-amd64.zip
• Linux: mcp-sqlserver-linux-amd64.tar.gz
• macOS Apple Silicon: mcp-sqlserver-darwin-arm64.tar.gz
• macOS Intel: mcp-sqlserver-darwin-amd64.tar.gz

If you clone this repository, you get source code only. The release packages are generated by GitHub Actions and attached to GitHub Releases.

Publishing a Release

Maintainers can publish release packages by pushing a version tag:

git tag v1.0.0
git push origin v1.0.0

GitHub Actions will build, test, archive, checksum, and upload the release assets.

Run

$env:SQL_SERVER_HOST = "localhost"
$env:SQL_SERVER_USER = "sa"
$env:SQL_SERVER_PASSWORD = "your_password"
$env:SQL_SERVER_DATABASE = "your_database"
go run ./cmd

Build

git clone https://github.com/TranHuyThang9999/mcp-sqlserver.git

go build -o mcp-sqlserver.exe ./cmd

Docker

Create a local .env file:

Copy-Item .env.example .env

Edit .env, then build the image:

docker build -t mcp-sqlserver:local .

Run as a stdio MCP process:

docker run --rm -i --env-file .env mcp-sqlserver:local

With Docker Compose:

docker compose run --rm mcp-sqlserver

When SQL Server runs on your Windows host, use SQL_SERVER_HOST=host.docker.internal in .env.

Codex MCP config

The installer can write this config for you. Use this section only when you want to configure Codex manually.

Codex does not use the mcpServers JSON format. Codex reads MCP servers from ~/.codex/config.toml, and you can manage the same config with codex mcp add / codex mcp list.

Replace <path-to-mcp-sqlserver.exe> with the executable path on your machine. On Windows, the auto-installer stores releases under:

%LOCALAPPDATA%\mcp-sqlserver\releases\<version>\mcp-sqlserver-windows-amd64\mcp-sqlserver.exe

Use this TOML in ~/.codex/config.toml:

[mcp_servers.sqlserver]
command = "<path-to-mcp-sqlserver.exe>"
startup_timeout_sec = 10
tool_timeout_sec = 60

[mcp_servers.sqlserver.env]
SQL_SERVER_HOST = "localhost"
SQL_SERVER_PORT = "1433"
SQL_SERVER_USER = "sa"
SQL_SERVER_PASSWORD = "your_password"
SQL_SERVER_DATABASE = "your_database"
SQL_SERVER_ENCRYPT = "disable"
SQL_SERVER_TRUST_CERT = "true"
MCP_SQLSERVER_MAX_ROWS = "500"
MCP_SQLSERVER_ALLOW_SCHEMA_CHANGES = "false"
MCP_SQLSERVER_ALLOW_DANGEROUS_SQL = "false"
MCP_SQLSERVER_ALLOW_PROCEDURE_CALLS = "true"

Docker-based Codex config:

[mcp_servers.sqlserver_docker]
command = "docker"
args = [
  "run",
  "--rm",
  "-i",
  "--env-file",
  "<path-to-project>\\.env",
  "mcp-sqlserver:local",
]
startup_timeout_sec = 20
tool_timeout_sec = 60

You can also add the executable server using the Codex CLI:

codex mcp add sqlserver `
  --env SQL_SERVER_HOST=localhost `
  --env SQL_SERVER_PORT=1433 `
  --env SQL_SERVER_USER=sa `
  --env SQL_SERVER_PASSWORD=your_password `
  --env SQL_SERVER_DATABASE=your_database `
  -- <path-to-mcp-sqlserver.exe>

Verify:

codex mcp list

The installer will create the config automatically.

Use the built executable as a stdio MCP server:

{
  "mcpServers": {
    "sqlserver": {
      "command": "<path-to-mcp-sqlserver.exe>",
      "env": {
        "SQL_SERVER_HOST": "localhost",
        "SQL_SERVER_USER": "sa",
        "SQL_SERVER_PASSWORD": "your_password",
        "SQL_SERVER_DATABASE": "your_database",
        "MCP_SQLSERVER_MAX_ROWS": "500"
      }
    }
  }
}

Docker-based MCP config:

{
  "mcpServers": {
    "sqlserver-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "<path-to-project>\\.env",
        "mcp-sqlserver:local"
      ]
    }
  }
}

During development you can run through Go:

{
  "mcpServers": {
    "sqlserver-dev": {
      "command": "go",
      "args": ["run", "./cmd"],
      "cwd": "<path-to-project>",
      "env": {
        "SQL_SERVER_HOST": "localhost",
        "SQL_SERVER_USER": "sa",
        "SQL_SERVER_PASSWORD": "your_password",
        "SQL_SERVER_DATABASE": "your_database"
      }
    }
  }
}

Tool list

SQL Tools

• health_check - Check SQL Server connectivity.
• sql_select - Run read-only SELECT/WITH queries.
• sql_execute - Run INSERT, UPDATE, DELETE, MERGE.
• list_databases - List databases.
• list_schemas - List schemas.
• list_tables - List tables and views.
• describe_table - Get table schema (columns, PKs, FKs, indexes, triggers).
• list_views - List views.
• get_object_definition - Get SP/view/trigger definition.
• list_procedures - List stored procedures.
• execute_procedure - Execute a stored procedure.
• list_triggers - List triggers.

RAG Knowledge Tools

• rag_query - Search learned schema knowledge.
• rag_learn_table - Manually learn a table schema.
• rag_stats - Get knowledge base statistics.
• rag_list_tables - List all learned tables.
• rag_list_relations - List all learned relationships.

Notes

Use a SQL Server login with the least permissions needed for your workflow. For agent usage, prefer a read-only account unless you explicitly need writes.