MCPQL

Name: MCPQL
Author: Hendrick Castro

Inspect, search and query Microsoft SQL Server and Azure SQL databases from an MCP client

By Hendrick Castro (individual) TypeScript Local · stdio Databases

GitHub npm Website

37 popularity score ★ 15 ↓ 645/wk

Connect your client

Local (npm)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

It needs DB_SERVER, DB_NAME, DB_USER, DB_PASSWORD. Replace each <NAME> with your value.

Claude CodeTerminal

claude mcp add mcpql -e DB_SERVER=<DB_SERVER> -e DB_NAME=<DB_NAME> -e DB_USER=<DB_USER> -e DB_PASSWORD=<DB_PASSWORD> -- npx -y mcpql

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": [
        "-y",
        "mcpql"
      ],
      "env": {
        "DB_SERVER": "<DB_SERVER>",
        "DB_NAME": "<DB_NAME>",
        "DB_USER": "<DB_USER>",
        "DB_PASSWORD": "<DB_PASSWORD>"
      }
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": [
        "-y",
        "mcpql"
      ],
      "env": {
        "DB_SERVER": "<DB_SERVER>",
        "DB_NAME": "<DB_NAME>",
        "DB_USER": "<DB_USER>",
        "DB_PASSWORD": "<DB_PASSWORD>"
      }
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "mcpql": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcpql"
      ],
      "env": {
        "DB_SERVER": "<DB_SERVER>",
        "DB_NAME": "<DB_NAME>",
        "DB_USER": "<DB_USER>",
        "DB_PASSWORD": "<DB_PASSWORD>"
      }
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.mcpql]
command = "npx"
args = ["-y", "mcpql"]

[mcp_servers.mcpql.env]
DB_SERVER = "<DB_SERVER>"
DB_NAME = "<DB_NAME>"
DB_USER = "<DB_USER>"
DB_PASSWORD = "<DB_PASSWORD>"

Gemini CLITerminal

gemini mcp add --scope user -e DB_SERVER=<DB_SERVER> -e DB_NAME=<DB_NAME> -e DB_USER=<DB_USER> -e DB_PASSWORD=<DB_PASSWORD> mcpql npx -- -y mcpql

Local (from source)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

It needs DB_SERVER, DB_NAME, DB_USER, DB_PASSWORD. Replace each <NAME> with your value.

FirstTerminal

git clone https://github.com/hendrickcastro/MCPQL.git
cd MCPQL
npm install
npm run build

Claude CodeTerminal

claude mcp add mcpql -e DB_SERVER=<DB_SERVER> -e DB_NAME=<DB_NAME> -e DB_USER=<DB_USER> -e DB_PASSWORD=<DB_PASSWORD> -- node '<ABSOLUTE_PATH_TO_CLONE>/dist/server.js'

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "mcpql": {
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/dist/server.js"
      ],
      "env": {
        "DB_SERVER": "<DB_SERVER>",
        "DB_NAME": "<DB_NAME>",
        "DB_USER": "<DB_USER>",
        "DB_PASSWORD": "<DB_PASSWORD>"
      }
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "mcpql": {
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/dist/server.js"
      ],
      "env": {
        "DB_SERVER": "<DB_SERVER>",
        "DB_NAME": "<DB_NAME>",
        "DB_USER": "<DB_USER>",
        "DB_PASSWORD": "<DB_PASSWORD>"
      }
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "mcpql": {
      "type": "stdio",
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/dist/server.js"
      ],
      "env": {
        "DB_SERVER": "<DB_SERVER>",
        "DB_NAME": "<DB_NAME>",
        "DB_USER": "<DB_USER>",
        "DB_PASSWORD": "<DB_PASSWORD>"
      }
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.mcpql]
command = "node"
args = ["<ABSOLUTE_PATH_TO_CLONE>/dist/server.js"]

[mcp_servers.mcpql.env]
DB_SERVER = "<DB_SERVER>"
DB_NAME = "<DB_NAME>"
DB_USER = "<DB_USER>"
DB_PASSWORD = "<DB_PASSWORD>"

Gemini CLITerminal

gemini mcp add --scope user -e DB_SERVER=<DB_SERVER> -e DB_NAME=<DB_NAME> -e DB_USER=<DB_USER> -e DB_PASSWORD=<DB_PASSWORD> mcpql node -- '<ABSOLUTE_PATH_TO_CLONE>/dist/server.js'

Settings 12

`DB_SERVER`	Required: SQL Server host name or IP (not needed when DB_CONNECTION_STRING is set).
`DB_NAME`	Required: Database to connect to.
`DB_USER`	Required: Login name for SQL, Windows or Azure AD password sign-in.
`DB_PASSWORD`	Required: Password for that login.
`DB_AUTHENTICATION_TYPE`	Optional: sql (default), windows or azure-ad.
`DB_CONNECTION_STRING`	Optional: Full connection string, used instead of the individual settings.
`DB_PORT`	Optional: Server port; the README gives 1433.
`DB_INSTANCE_NAME`	Optional: Named instance such as SQLEXPRESS.
`DB_DOMAIN`	Optional: Windows domain; required when DB_AUTHENTICATION_TYPE is windows.
`DB_AZURE_CLIENT_ID`	Optional: Service principal client ID for azure-ad; also set DB_AZURE_CLIENT_SECRET and DB_AZURE_TENANT_ID.
`DB_ENCRYPT`	Optional: Encrypt the connection (default false).
`DB_ALLOW_MODIFICATIONS`	Optional: Allow write and DDL queries (default false); DB_ALLOW_STORED_PROCEDURES does the same for procedures.

What it does

MCPQL is a local stdio server for Microsoft SQL Server and Azure SQL Database. It connects through the mssql driver and gives an assistant tools to look at a database's structure: table columns, keys, indexes and constraints, stored procedure parameters and source, and the dependencies between objects. It can also search object names and definitions, preview rows, profile a column or a whole table, and run SQL or stored procedures.

It starts read-only. Version 1.1.0 (dist/security.js) refuses a query passed to mcp_execute_query if its text contains any of the words INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, MERGE, BULK, EXEC or EXECUTE, unless DB_ALLOW_MODIFICATIONS is true. mcp_execute_procedure is refused unless DB_ALLOW_STORED_PROCEDURES is true. This is a word filter on the query text, not a database permission. GRANT, DENY, REVOKE and SELECT ... INTO are not on the list, and a read query that uses one of the listed words, such as a column called Update, is blocked.

It signs in with SQL Server logins (the default), Windows NTLM with a domain, Azure AD user and password, an Azure AD service principal, or a full connection string in DB_CONNECTION_STRING. It opens the connection on the first tool call, not at startup.

What it needs

Runtime	Node.js 18+

Node.js 18 or later for npx. A reachable SQL Server 2016+ or Azure SQL database and a login for it: a SQL login by default, or a Windows domain account (DB_DOMAIN is required for that mode), or Azure AD credentials. For Azure SQL, a server firewall rule that admits your IP. For SQL Server Express, TCP/IP must be enabled and DB_INSTANCE_NAME set.

Limits

SQL Server and Azure SQL only. Object names must be schema-qualified (dbo.Users). mcp_preview_data returns 100 rows by default, up to 1000 with limit. mcp_get_sample_values returns 10 values by default. mcp_quick_data_analysis samples 1000 rows by default. Connection and request timeouts default to 30 seconds. With DB_AUTHENTICATION_TYPE=azure-ad the code always turns encryption on and certificate trust off, whatever DB_ENCRYPT says (src/db.ts). The README's own snippets run npx -y hendrickcastro/mcpql, which fetches the GitHub repository; the published npm package is mcpql.

Who it suits

It suits developers and DBAs who work on SQL Server and want an assistant to explore a schema, trace dependencies or profile data, mostly read-only. It runs on your own machine with your own database login. Read-only depends on a keyword filter, so give it a login that only has read rights on production instead of relying on the default settings. It is a community project, not a Microsoft one. If you need a database other than SQL Server, pick a server made for that engine.

Tools 11

mcp_table_analysis: Shows a table's columns, keys, indexes and constraints
mcp_sp_structure: Shows a stored procedure's parameters, dependencies and source
mcp_preview_data: Returns rows from a table, with optional column filters and a row limit
mcp_get_column_stats: Computes statistics for one column
mcp_execute_procedure: Runs a stored procedure with parameters; off unless DB_ALLOW_STORED_PROCEDURES is true
mcp_execute_query: Runs a SQL query; write keywords need DB_ALLOW_MODIFICATIONS
mcp_quick_data_analysis: Profiles a table: row count, column distributions and top values
mcp_search_comprehensive: Searches object names and definitions, optionally by object type
mcp_get_dependencies: Lists what a table, view or procedure depends on and what depends on it
mcp_get_sample_values: Returns the most frequent distinct values of a column
mcp_get_security_status: Reports whether modifications and stored procedures are enabled

Popularity

37 popularity score, on our list (the bar is 36)

★ 15 ↓ 645/wk

GitHub stars	15	14.4 points
npm downloads, last week	645	22.5 points

Measured 2026-11-07. How the score works.

Where it is published

Code	hendrickcastro/mcpql ★ 15
npm	mcpql 1.1.0, 2026-01-22

What it can reach

Runs	On your machine
Reaches	A database, The internet, Files on your machine
Changes things	Yes: it can write, send, create or delete
Sign-in	Other
Licence	MIT (npm)
Last code change	2026-01-30

Runs locally over stdio and connects over the network to the SQL Server you configure, using credentials taken from environment variables or a .env file in the working directory. By default it blocks queries containing modification keywords and blocks stored procedure calls. The block is a text check: it does not cover GRANT, DENY, REVOKE or SELECT ... INTO, and procedures may write once enabled. With DB_ALLOW_MODIFICATIONS=true, mcp_execute_query can insert, update, delete, drop or create. Version 1.1.0 appends a debug log, mcp_debug.log, in the package's install folder and logs query text to stderr. Only the database login's own rights limit what it can read.

Over time

GitHub stars 15 +0

1515

13 Oct 20267 Nov 2026

npm downloads a week 645 +627 (+3483 %)

5.2k18

2 Feb 20267 Nov 2026

Before the site measured it, read from npm's daily download counts.

Popularity score 37 −2 (−4 %)

4031

13 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-14.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![MCPQL on EveryMCPServer](https://everymcpserver.com/badge/mcpql.svg)](https://everymcpserver.com/servers/mcpql)

Connect your client

Add in one click

Or add it by command or config

Add in one click

Or add it by command or config

Settings 12

What it does

What it needs

Limits

Who it suits

Tools 11

Similar servers

MySQL MCP Server

Azure MCP Server

MCP Toolbox for Databases

OmniSQL MCP

ClickHouse MCP Server

dbt MCP Server