# mcp-server-mssql

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/Model_Context_Protocol-server-green.svg)](https://modelcontextprotocol.io/)

A [Model Context Protocol](https://modelcontextprotocol.io/) server that gives LLM agents safe, structured access to Microsoft SQL Server: schema inspection plus row-level CRUD, every operation parameterized and logged.

Built because agents working against real business databases need more than "run this SQL string" — they need typed tools with predictable failure modes.

## How it works

```mermaid
flowchart LR
    A[MCP client<br/>Claude Desktop / Claude Code] -- stdio --> B[mcp-server-mssql]
    B --> C[connection pool<br/>mssql driver]
    C --> D[(SQL Server)]
    B -. structured logs .-> E[logs/]
```

The server connects to a single database configured via environment variables and exposes six tools. All queries are parameterized — table and column names are validated against the live schema before any statement runs, so an agent cannot inject through identifiers.

## Tools

| Tool | What it does |
|---|---|
| `list_tables` | List all user tables in the configured database |
| `get_table_schema` | Column names, types, nullability, and defaults for a table |
| `read_table_rows` | Read rows with optional column selection, WHERE filters, ORDER BY, and LIMIT |
| `create_table_records` | Insert one or more rows (column/value validated against schema) |
| `update_table_records` | Update rows matching a filter; returns affected count |
| `delete_table_records` | Delete rows matching a filter; returns affected count |

### Example interaction

> **User:** "Which customers signed up this month?"
>
> **Agent** calls `list_tables` → finds `Customers` → calls `get_table_schema {"table_name": "Customers"}` → sees `CreatedAt datetime2` → calls `read_table_rows {"table_name": "Customers", "filters": {"CreatedAt": {">=": "2026-07-01"}}, "limit": 50}` → answers with the rows.

## Setup

Requires Node.js 18+ and network access to a SQL Server instance.

```bash
git clone https://github.com/TerraCo89/mcp-server-mssql.git
cd mcp-server-mssql
npm install
cp .env.example .env   # fill in connection details
npm run build
```

### Configuration (environment variables)

| Variable | Required | Notes |
|---|---|---|
| `MSSQL_HOST` / `MSSQL_PORT` | yes / no | Port defaults to 1433 |
| `MSSQL_USER` / `MSSQL_PASSWORD` | yes | SQL auth credentials |
| `MSSQL_DATABASE` | yes | Single database per server instance |
| `MSSQL_ENCRYPT`, `MSSQL_TRUST_SERVER_CERTIFICATE` | no | TLS options |
| `LOG_LEVEL` | no | `info` by default |

### Use with Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["/path/to/mcp-server-mssql/dist/server.js"],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_USER": "agent_reader",
        "MSSQL_PASSWORD": "...",
        "MSSQL_DATABASE": "MyDb"
      }
    }
  }
}
```

Tip: point it at a least-privilege SQL login — the server can only do what the login can.

## Development

```bash
npm run dev    # ts-node with live reload
npm test       # jest test suite (src/*.test.ts, tests/)
npm run build  # emit dist/
```

Docker: `docker build -t mcp-server-mssql .` then run with the same environment variables.

## License

[MIT](LICENSE)