MCPQL - SQL Server MCP Server

1.1.0 verified Sat Apr 25 auth: no javascript

MCPQL (v1.1.0) is a Model Context Protocol server for SQL Server database analysis and operations, targeting Node.js 18+. It provides 10 tools for database analysis, object discovery, and data manipulation via MCP. Differentiators: native MCP protocol support, works with Claude Desktop/Cursor IDE/Trae AI, supports SQL Server 2016+ and Azure SQL, Docker-ready. Released under MIT, actively maintained.

Common errors

error require is not defined in ES module scope ↓

cause Using CommonJS require() to load an ESM-only package.

fix

Switch to import syntax or set type: 'module' in package.json.

error Cannot find module 'mcpql' ↓

cause Package not installed or not in node_modules.

fix

Run npm install mcpql or use npx. Check that you are in the correct directory.

error ConnectionError: Failed to connect to server: localhost in 15000ms ↓

cause SQL Server not reachable, wrong credentials, or firewall blocking port 1433.

fix

Verify DB_SERVER, DB_PORT, DB_USER, DB_PASSWORD environment variables. Check network connectivity and SQL Server instance configuration.

Warnings

breaking Package is ESM-only; CommonJS require() will throw error. ↓

fix Use import syntax or ensure your project is configured for ESM (e.g., type: 'module' in package.json).

deprecated Support for Node.js <18 will be removed in v2. ↓

fix Upgrade Node.js to version 18 or later.

gotcha Database connection credentials (DB_PASSWORD, etc.) are passed as environment variables; accidental exposure in logs or client configs is a security risk. ↓

fix Use secure credential management (e.g., secret managers) and avoid hardcoding in config files.

gotcha The server expects MCP messages on stdin/stdout; not suitable for use as an HTTP API without additional adaptation. ↓

fix Use the server within an MCP-compatible host (e.g., Claude Desktop) or wrap with an MCP-to-HTTP bridge.

gotcha When using npx, the `-y` flag may not work in all environments (e.g., restricted network); pre-install locally instead. ↓

fix Use local installation: npm install -g mcpql or run via Docker.

Install

npm install mcpql

yarn add mcpql

pnpm add mcpql

Imports

startServer
wrong
```
const startServer = require('mcpql')
```
correct
```
import { startServer } from 'mcpql'
```
Package is ESM-only since v1.0.0; CommonJS require will fail.
MCPQLConfig
```
import { MCPQLConfig } from 'mcpql'
```
TypeScript type export; use for config type safety.
default
wrong
```
import * as mcpql from 'mcpql'
```
correct
```
import mcpql from 'mcpql'
```
Default export exposes the main server factory function; namespace import may break.

Quickstart

Shows how to start the MCPQL server programmatically with environment variable based SQL Server configuration.

import { startServer } from 'mcpql';

const config = {
  authentication: {
    type: 'sql',
    options: {
      userName: process.env.DB_USER ?? 'sa',
      password: process.env.DB_PASSWORD ?? '',
    },
  },
  server: process.env.DB_SERVER ?? 'localhost',
  port: parseInt(process.env.DB_PORT ?? '1433', 10),
  database: process.env.DB_NAME ?? 'master',
  options: {
    encrypt: process.env.DB_ENCRYPT === 'true',
    trustServerCertificate: process.env.DB_TRUST_SERVER_CERTIFICATE === 'true',
  },
};

startServer(config).catch(console.error);