@adriancy/mcp-mssql 1.0.0

package/.env.example

@@ -0,0 +1,21 @@
+# Required
+MSSQL_SERVER=localhost
+MSSQL_USER=sa
+MSSQL_PASSWORD=
+MSSQL_DATABASE=master
+
+# Optional (default 1433)
+# MSSQL_PORT=1433
+
+# TLS (defaults: encrypt true, trust cert false)
+# MSSQL_ENCRYPT=true
+# MSSQL_TRUST_SERVER_CERTIFICATE=false
+
+# Safety: when false/ unset, blocks common write/DDL/exec patterns (heuristic only)
+# MSSQL_ALLOW_WRITES=false
+
+# Cap rows returned (SET ROWCOUNT); unset = no cap
+# MSSQL_MAX_ROWS=5000
+
+# Request timeout in ms (driver)
+# MSSQL_QUERY_TIMEOUT_MS=30000

package/README.md

@@ -0,0 +1,98 @@
+# mssql-mcp
+
+MCP server (stdio) that connects to Microsoft SQL Server using the `mssql` driver. Tool arguments are defined and validated with [Valibot](https://valibot.dev); JSON Schema for clients is generated with `@valibot/to-json-schema`.
+
+**Implementation note:** This project uses the low-level `@modelcontextprotocol/sdk` `Server` class rather than `McpServer`, because the current SDK’s `McpServer.registerTool` path is built around Zod for schema export and validation. Tools are registered with `ListTools` / `tools/call` handlers and Valibot parsing inside the handlers.
+
+## Tools
+
+- **`mssql_query`** — Run a T-SQL batch; returns `recordsets` and `rowsAffected`. Honors `MSSQL_MAX_ROWS` via `SET ROWCOUNT` when set.
+- **`mssql_list_tables`** — Base tables from `INFORMATION_SCHEMA.TABLES`, optional schema filter.
+- **`mssql_describe_table`** — Column metadata from `INFORMATION_SCHEMA.COLUMNS`.
+
+## Environment variables
+
+See [`.env.example`](.env.example). Required: `MSSQL_SERVER`, `MSSQL_USER`, `MSSQL_PASSWORD`, `MSSQL_DATABASE`.
+
+- **`MSSQL_ALLOW_WRITES`** — Default off. When off, a heuristic blocks common write/DDL/exec keywords (not a substitute for DB permissions).
+- **`MSSQL_MAX_ROWS`** — When set, wraps batches in `SET ROWCOUNT` for `mssql_query`.
+- **`MSSQL_ENCRYPT`** / **`MSSQL_TRUST_SERVER_CERTIFICATE`** — Passed through to the driver (`encrypt` defaults to true).
+
+## Build and run
+
+```bash
+pnpm install
+pnpm run build
+pnpm start
+```
+
+Development (no separate build):
+
+```bash
+pnpm dev
+```
+
+Do not write logs to **stdout** when running under MCP; the protocol uses stdout. Errors on startup go to stderr via `console.error`.
+
+## Cursor MCP configuration
+
+**Published package (`npx`):** from `@adriancy/mssql-mcp` **1.0.1+** you can run the CLI without a local path:
+
+```json
+{
+  "mcpServers": {
+    "mssql": {
+      "command": "npx",
+      "args": ["-y", "@adriancy/mssql-mcp"],
+      "env": {
+        "MSSQL_SERVER": "localhost",
+        "MSSQL_USER": "your_user",
+        "MSSQL_PASSWORD": "your_password",
+        "MSSQL_DATABASE": "your_database",
+        "MSSQL_TRUST_SERVER_CERTIFICATE": "true"
+      }
+    }
+  }
+}
+```
+
+**Local checkout:** use the absolute path to `dist/index.js`:
+
+```json
+{
+  "mcpServers": {
+    "mssql": {
+      "command": "node",
+      "args": ["/home/adrian/code/mcp/mssql-mcp/dist/index.js"],
+      "env": {
+        "MSSQL_SERVER": "localhost",
+        "MSSQL_USER": "your_user",
+        "MSSQL_PASSWORD": "your_password",
+        "MSSQL_DATABASE": "your_database",
+        "MSSQL_TRUST_SERVER_CERTIFICATE": "true"
+      }
+    }
+  }
+}
+```
+
+Use **`node`** for local paths. Do **not** use **`pnpm`** as `command` for MCP: if pnpm prints errors to stdout, Cursor can show JSON parse errors because the protocol uses stdout. **`npx`** is fine for the published package: it execs the `mssql-mcp` bin (Node) after install.
+
+### Dev mode without a build (still use `node`)
+
+Set **`cwd`** to this repo so `node` can resolve `tsx` from `node_modules`:
+
+```json
+{
+  "mcpServers": {
+    "mssql": {
+      "command": "node",
+      "args": ["--import", "tsx", "/home/adrian/code/mcp/src/index.ts"],
+      "cwd": "/home/adrian/code/mcp",
+      "env": { }
+    }
+  }
+}
+```
+
+Fill `env` the same as in the example above. Run `pnpm install` locally first so `tsx` exists.

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+export type AppConfig = {
+    server: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+    encrypt: boolean;
+    trustServerCertificate: boolean;
+    allowWrites: boolean;
+    maxRows: number | undefined;
+    queryTimeoutMs: number | undefined;
+};
+export declare function loadConfig(): AppConfig;
+export declare function mssqlDriverConfig(cfg: AppConfig): import('mssql').config;

package/dist/config.js

@@ -0,0 +1,74 @@
+import * as v from 'valibot';
+function parseBool(raw, defaultValue) {
+    if (raw === undefined || raw === '')
+        return defaultValue;
+    return /^(1|true|yes|on)$/i.test(raw);
+}
+function parseIntEnv(raw, defaultValue) {
+    if (raw === undefined || raw === '')
+        return defaultValue;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) ? n : defaultValue;
+}
+const envSchema = v.object({
+    MSSQL_SERVER: v.pipe(v.string(), v.nonEmpty()),
+    MSSQL_USER: v.pipe(v.string(), v.nonEmpty()),
+    MSSQL_PASSWORD: v.string(),
+    MSSQL_DATABASE: v.pipe(v.string(), v.nonEmpty()),
+    MSSQL_PORT: v.optional(v.string()),
+    MSSQL_ENCRYPT: v.optional(v.string()),
+    MSSQL_TRUST_SERVER_CERTIFICATE: v.optional(v.string()),
+    MSSQL_ALLOW_WRITES: v.optional(v.string()),
+    MSSQL_MAX_ROWS: v.optional(v.string()),
+    MSSQL_QUERY_TIMEOUT_MS: v.optional(v.string()),
+});
+export function loadConfig() {
+    const e = v.parse(envSchema, {
+        MSSQL_SERVER: process.env.MSSQL_SERVER,
+        MSSQL_USER: process.env.MSSQL_USER,
+        MSSQL_PASSWORD: process.env.MSSQL_PASSWORD,
+        MSSQL_DATABASE: process.env.MSSQL_DATABASE,
+        MSSQL_PORT: process.env.MSSQL_PORT,
+        MSSQL_ENCRYPT: process.env.MSSQL_ENCRYPT,
+        MSSQL_TRUST_SERVER_CERTIFICATE: process.env.MSSQL_TRUST_SERVER_CERTIFICATE,
+        MSSQL_ALLOW_WRITES: process.env.MSSQL_ALLOW_WRITES,
+        MSSQL_MAX_ROWS: process.env.MSSQL_MAX_ROWS,
+        MSSQL_QUERY_TIMEOUT_MS: process.env.MSSQL_QUERY_TIMEOUT_MS,
+    });
+    const port = parseIntEnv(e.MSSQL_PORT, 1433);
+    const maxRowsRaw = e.MSSQL_MAX_ROWS;
+    const maxRows = maxRowsRaw === undefined || maxRowsRaw === ''
+        ? undefined
+        : Math.max(0, parseIntEnv(maxRowsRaw, 0));
+    const timeoutRaw = e.MSSQL_QUERY_TIMEOUT_MS;
+    const queryTimeoutMs = timeoutRaw === undefined || timeoutRaw === ''
+        ? undefined
+        : Math.max(0, parseIntEnv(timeoutRaw, 0));
+    return {
+        server: e.MSSQL_SERVER,
+        port,
+        user: e.MSSQL_USER,
+        password: e.MSSQL_PASSWORD,
+        database: e.MSSQL_DATABASE,
+        encrypt: parseBool(e.MSSQL_ENCRYPT, true),
+        trustServerCertificate: parseBool(e.MSSQL_TRUST_SERVER_CERTIFICATE, false),
+        allowWrites: parseBool(e.MSSQL_ALLOW_WRITES, false),
+        maxRows: maxRows === 0 ? undefined : maxRows,
+        queryTimeoutMs: queryTimeoutMs === 0 ? undefined : queryTimeoutMs,
+    };
+}
+export function mssqlDriverConfig(cfg) {
+    return {
+        user: cfg.user,
+        password: cfg.password,
+        server: cfg.server,
+        port: cfg.port,
+        database: cfg.database,
+        pool: { max: 10, min: 0, idleTimeoutMillis: 30_000 },
+        options: {
+            encrypt: cfg.encrypt,
+            trustServerCertificate: cfg.trustServerCertificate,
+        },
+        requestTimeout: cfg.queryTimeoutMs,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import sql from 'mssql';
+import * as v from 'valibot';
+import { Server } from '@modelcontextprotocol/sdk/server';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { loadConfig, mssqlDriverConfig } from './config.js';
+import { assertReadOnlySql, wrapWithRowCount } from './readonly-sql.js';
+import { mssqlDescribeTableSchema, mssqlListTablesSchema, mssqlQuerySchema, valibotToJsonSchema, } from './schemas.js';
+const SHARED_TOOL_PREAMBLE = 'Connection uses MSSQL_* environment variables on the MCP server process. Arbitrary SQL is dangerous; prefer a read-only or narrowly scoped database user.';
+function toolError(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
+function jsonResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+async function runQuery(pool, cfg, batch) {
+    assertReadOnlySql(batch, cfg.allowWrites);
+    const wrapped = wrapWithRowCount(batch, cfg.maxRows);
+    const result = await pool.request().query(wrapped);
+    const recordsets = result.recordsets;
+    return jsonResult({
+        rowsAffected: result.rowsAffected,
+        recordsets,
+        rowCountNote: cfg.maxRows !== undefined
+            ? `ROWCOUNT capped at ${cfg.maxRows} per batch (SET ROWCOUNT).`
+            : undefined,
+    });
+}
+async function runListTables(pool, schemaFilter) {
+    const req = pool.request();
+    req.input('schema', sql.NVarChar(128), schemaFilter ?? null);
+    const q = `
+SELECT TABLE_SCHEMA, TABLE_NAME, TABLE_TYPE
+FROM INFORMATION_SCHEMA.TABLES
+WHERE TABLE_TYPE = 'BASE TABLE'
+  AND (@schema IS NULL OR TABLE_SCHEMA = @schema)
+ORDER BY TABLE_SCHEMA, TABLE_NAME`;
+    const result = await req.query(q);
+    return jsonResult({ tables: result.recordset });
+}
+async function runDescribeTable(pool, schema, table) {
+    const req = pool.request();
+    req.input('s', sql.NVarChar(128), schema);
+    req.input('t', sql.NVarChar(128), table);
+    const q = `
+SELECT
+  COLUMN_NAME,
+  DATA_TYPE,
+  IS_NULLABLE,
+  CHARACTER_MAXIMUM_LENGTH,
+  NUMERIC_PRECISION,
+  NUMERIC_SCALE,
+  ORDINAL_POSITION
+FROM INFORMATION_SCHEMA.COLUMNS
+WHERE TABLE_SCHEMA = @s AND TABLE_NAME = @t
+ORDER BY ORDINAL_POSITION`;
+    const result = await req.query(q);
+    return jsonResult({ columns: result.recordset });
+}
+function buildTools() {
+    return [
+        {
+            name: 'mssql_query',
+            description: `${SHARED_TOOL_PREAMBLE} Runs a T-SQL batch; returns recordsets as JSON.`,
+            inputSchema: valibotToJsonSchema(mssqlQuerySchema),
+        },
+        {
+            name: 'mssql_list_tables',
+            description: `${SHARED_TOOL_PREAMBLE} Lists BASE TABLE rows from INFORMATION_SCHEMA.TABLES.`,
+            inputSchema: valibotToJsonSchema(mssqlListTablesSchema),
+        },
+        {
+            name: 'mssql_describe_table',
+            description: `${SHARED_TOOL_PREAMBLE} Returns column metadata from INFORMATION_SCHEMA.COLUMNS.`,
+            inputSchema: valibotToJsonSchema(mssqlDescribeTableSchema),
+        },
+    ];
+}
+async function main() {
+    const cfg = loadConfig();
+    const pool = await sql.connect(mssqlDriverConfig(cfg));
+    const server = new Server({ name: 'mssql-mcp', version: '1.0.0' });
+    server.registerCapabilities({ tools: { listChanged: false } });
+    const tools = buildTools();
+    server.setRequestHandler(ListToolsRequestSchema, () => ({ tools }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const name = request.params.name;
+        const rawArgs = request.params.arguments ?? {};
+        try {
+            switch (name) {
+                case 'mssql_query': {
+                    const args = v.parse(mssqlQuerySchema, rawArgs);
+                    return await runQuery(pool, cfg, args.sql);
+                }
+                case 'mssql_list_tables': {
+                    const args = v.parse(mssqlListTablesSchema, rawArgs);
+                    return await runListTables(pool, args.schema);
+                }
+                case 'mssql_describe_table': {
+                    const args = v.parse(mssqlDescribeTableSchema, rawArgs);
+                    return await runDescribeTable(pool, args.schema, args.table);
+                }
+                default:
+                    return toolError(`Unknown tool: ${name}`);
+            }
+        }
+        catch (err) {
+            if (v.isValiError(err)) {
+                return toolError(`Invalid arguments: ${err.message}`);
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            return toolError(msg);
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/readonly-sql.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Best-effort read-only gate. Not a substitute for database permissions.
+ */
+export declare function stripSqlComments(text: string): string;
+/** Masks single-quoted and N'...' string literals so keywords inside literals are ignored. */
+export declare function maskSqlStringLiterals(text: string): string;
+export declare function assertReadOnlySql(sql: string, allowWrites: boolean): void;
+export declare function wrapWithRowCount(sql: string, maxRows: number | undefined): string;

package/dist/readonly-sql.js

@@ -0,0 +1,66 @@
+/**
+ * Best-effort read-only gate. Not a substitute for database permissions.
+ */
+const FORBIDDEN = /\b(INSERT|UPDATE|DELETE|MERGE|DROP|ALTER|CREATE|TRUNCATE|EXEC|EXECUTE|GRANT|REVOKE|DENY|BULK)\b/i;
+export function stripSqlComments(text) {
+    let s = text.replace(/\/\*[\s\S]*?\*\//g, ' ');
+    s = s.replace(/--[^\n\r]*/g, ' ');
+    return s;
+}
+/** Masks single-quoted and N'...' string literals so keywords inside literals are ignored. */
+export function maskSqlStringLiterals(text) {
+    let out = '';
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === "'") {
+            let j = i + 1;
+            while (j < text.length) {
+                if (text[j] === "'" && text[j + 1] === "'") {
+                    j += 2;
+                    continue;
+                }
+                if (text[j] === "'")
+                    break;
+                j++;
+            }
+            out += ' ';
+            i = j < text.length ? j + 1 : text.length;
+            continue;
+        }
+        if (ch === 'N' || ch === 'n') {
+            if (text[i + 1] === "'") {
+                let j = i + 2;
+                while (j < text.length) {
+                    if (text[j] === "'" && text[j + 1] === "'") {
+                        j += 2;
+                        continue;
+                    }
+                    if (text[j] === "'")
+                        break;
+                    j++;
+                }
+                out += ' ';
+                i = j < text.length ? j + 1 : text.length;
+                continue;
+            }
+        }
+        out += ch;
+        i++;
+    }
+    return out;
+}
+export function assertReadOnlySql(sql, allowWrites) {
+    if (allowWrites)
+        return;
+    const probe = maskSqlStringLiterals(stripSqlComments(sql));
+    if (FORBIDDEN.test(probe)) {
+        throw new Error('Read-only mode: this batch contains a blocked keyword (INSERT, UPDATE, DELETE, MERGE, DDL, EXEC, etc.). Set MSSQL_ALLOW_WRITES=true to allow writes (still use a least-privilege login).');
+    }
+}
+export function wrapWithRowCount(sql, maxRows) {
+    if (maxRows === undefined || maxRows <= 0)
+        return sql;
+    const n = Math.floor(maxRows);
+    return `SET ROWCOUNT ${n}; ${sql}; SET ROWCOUNT 0;`;
+}

package/dist/schemas.d.ts

@@ -0,0 +1,16 @@
+import * as v from 'valibot';
+/** MCP tool inputSchema: JSON Schema derived from Valibot (descriptions flow to clients). */
+export declare function valibotToJsonSchema(schema: v.GenericSchema): Record<string, unknown>;
+export declare const mssqlQuerySchema: v.ObjectSchema<{
+    readonly sql: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.NonEmptyAction<string, undefined>, v.DescriptionAction<string, "T-SQL batch to run on the connected database. Credentials and safety flags come from server environment variables. Read-only mode blocks common write/DDL/exec patterns heuristically; use MSSQL_ALLOW_WRITES=true to lift that gate (still use a least-privilege SQL login).">]>;
+}, undefined>;
+export declare const mssqlListTablesSchema: v.ObjectSchema<{
+    readonly schema: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.DescriptionAction<string, "When set, restrict to this schema (e.g. dbo). When omitted, list base tables from all schemas.">]>, undefined>;
+}, undefined>;
+export declare const mssqlDescribeTableSchema: v.ObjectSchema<{
+    readonly schema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.NonEmptyAction<string, undefined>, v.DescriptionAction<string, "Schema name, typically dbo.">]>;
+    readonly table: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.NonEmptyAction<string, undefined>, v.DescriptionAction<string, "Table name (unquoted identifier).">]>;
+}, undefined>;
+export type MssqlQueryInput = v.InferOutput<typeof mssqlQuerySchema>;
+export type MssqlListTablesInput = v.InferOutput<typeof mssqlListTablesSchema>;
+export type MssqlDescribeTableInput = v.InferOutput<typeof mssqlDescribeTableSchema>;

package/dist/schemas.js

@@ -0,0 +1,18 @@
+import * as v from 'valibot';
+import { toJsonSchema } from '@valibot/to-json-schema';
+/** MCP tool inputSchema: JSON Schema derived from Valibot (descriptions flow to clients). */
+export function valibotToJsonSchema(schema) {
+    const js = toJsonSchema(schema);
+    delete js.$schema;
+    return js;
+}
+export const mssqlQuerySchema = v.object({
+    sql: v.pipe(v.string(), v.nonEmpty(), v.description('T-SQL batch to run on the connected database. Credentials and safety flags come from server environment variables. Read-only mode blocks common write/DDL/exec patterns heuristically; use MSSQL_ALLOW_WRITES=true to lift that gate (still use a least-privilege SQL login).')),
+});
+export const mssqlListTablesSchema = v.object({
+    schema: v.optional(v.pipe(v.string(), v.description('When set, restrict to this schema (e.g. dbo). When omitted, list base tables from all schemas.'))),
+});
+export const mssqlDescribeTableSchema = v.object({
+    schema: v.pipe(v.string(), v.nonEmpty(), v.description('Schema name, typically dbo.')),
+    table: v.pipe(v.string(), v.nonEmpty(), v.description('Table name (unquoted identifier).')),
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@adriancy/mcp-mssql",
+  "version": "1.0.0",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mssql-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    ".env.example"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.0",
+    "@valibot/to-json-schema": "^1.6.0",
+    "mssql": "^11.0.1",
+    "valibot": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/mssql": "^9.1.8",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "node --import tsx src/index.ts"
+  }
+}