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.