mcpql

library1.1.0jsnpmunverified

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.

database

npm install mcpql

github ↗package ↗

INSTALL

IMPORT

SIG · MCPQL

mcpql

databasejavascriptv1.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

startServer

✓ import { startServer } from 'mcpql'

✗ const startServer = require('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

✓ import mcpql from 'mcpql'

✗ import * as mcpql from 'mcpql'

Default export exposes the main server factory function; namespace import may break.

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);

Debug

Known issues

breakingPackage 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).

affects: >=1.0.0

deprecatedSupport for Node.js <18 will be removed in v2.

fix

Upgrade Node.js to version 18 or later.

affects: >=1.0.0 <2.0.0

gotchaDatabase 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.

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

gotchaWhen 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.

affects: >=1.0.0

Errors

Common errors & fixes

require is not defined in ES module scope

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

fix

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

Cannot find module 'mcpql'

Package not installed or not in node_modules.

fix

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

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

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.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredMCP protocol implementation

mssqlrequiredSQL Server database client

tediousoptionalUnderlying SQL Server driver for mssql

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/hendrickcastro/MCPQL ↗

packagehttps://www.npmjs.com/package/mcpql ↗