SQL Query Tools MCP Server
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SQL Query Tools MCP Servershow me the schema of the Orders table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
SQL Query Tools β MCP Server
MCP (Model Context Protocol) server for connecting to SQL Server in readonly mode. Allows any MCP client (Claude Desktop, GEAI, Cursor, etc.) to explore the schema and run SELECT queries against a SQL Server database.
π VersiΓ³n en espaΓ±ol
Installation
1. Install dependencies
Open a terminal inside the project folder and run:
npm install2. Configure the connection
The .env file is already included with the variables ready. Fill it in with your server details:
# Connection
SQL_SERVER=my_server
SQL_DATABASE=MyDatabase
SQL_USER=my_user
SQL_PASSWORD=my_password
SQL_INSTANCE= # leave empty if not using a named instance
SQL_ENCRYPT=false # set to true for Azure SQL or cloud servers
SQL_TRUST_SERVER_CERT=true
# Security / filters
ALLOWED_TABLES= # leave empty to expose all tables (supports wildcards: dbo.prefix_*)
MAX_ROWS=200 # maximum rows returned per query
# Performance
SQL_QUERY_TIMEOUT=30000 # query timeout in milliseconds (default: 30s)
SCHEMA_CACHE_TTL_MINUTES=5 # how long to cache schema results in memory (default: 5 min)
# Audit log
AUDIT_LOG=false # set to true to enable audit logging
AUDIT_LOG_DIR=./logs # folder where daily log files are writtenIf
SQL_ENCRYPTistrue(cloud servers), make sure to also setSQL_TRUST_SERVER_CERT=true.
3. Verify the connection
npm run test-connectionYou should see β
Connection successful! along with the SQL Server version and available tables.
4. Verify the MCP server starts
node mcp-server.jsYou should see β
MCP server connected and ready. Close it with Ctrl+C β the MCP client starts it automatically when needed.
Related MCP server: mcp-mssqlserver
Connect from your MCP client
Claude Desktop
Open the Claude Desktop configuration file:
Windows:
%APPDATA%\Claude\claude_desktop_config.jsonMac:
~/Library/Application Support/Claude/claude_desktop_config.json
Add the
sql-query-toolsblock insidemcpServers(replace the path):
{
"mcpServers": {
"sql-query-tools": {
"command": "node",
"args": ["ABSOLUTE_PATH/SQLQueryTools/mcp-server.js"]
}
}
}Restart Claude Desktop from the system tray (right-click β Quit, then reopen).
Verify the tools icon (π§) appears in the chat β clicking it should show the
db_*tools.
GEAI or other clients
Point the client to the mcp-sql-config.json file included in this folder, or configure it manually with the absolute path to mcp-server.js. Credentials are read from .env automatically.
Cursor
Open Settings β MCP.
Add the same JSON block from above.
Restart Cursor.
Available tools
Tool | Description |
| Tests the connection and returns server version and current datetime |
| Lists all tables and views with their column count (result is cached) |
| Returns column details (name, type, nullable) for a specific table or view |
| Returns 5 sample rows from a table β useful for the agent to understand the data |
| Executes a SELECT query (auto-injects TOP if no row limit is present) |
| Returns info about the currently connected database |
Configuration reference
Security β ALLOWED_TABLES
Controls which tables and views are accessible. Leave empty to expose everything.
ALLOWED_TABLES=dbo.Orders,dbo.Customers,dbo.Invoice_*Wildcards are supported at the end of the name (dbo.prefix_*). The filter applies to db_describe_schema, db_describe_table, and db_run_readonly.
Row limit β MAX_ROWS
Maximum number of rows returned by any SELECT query. The server automatically injects TOP N if the query doesn't include a limit.
MAX_ROWS=200Query timeout β SQL_QUERY_TIMEOUT
If a query takes longer than this value (in milliseconds), it is automatically cancelled. Prevents slow or heavy queries from blocking the server.
SQL_QUERY_TIMEOUT=30000 # 30 secondsSchema cache β SCHEMA_CACHE_TTL_MINUTES
db_describe_schema results are cached in memory to avoid repeated database roundtrips. After the TTL expires, the next call refreshes the cache.
SCHEMA_CACHE_TTL_MINUTES=5 # cache lasts 5 minutesSet to 0 to disable caching (always queries the database).
Audit log β AUDIT_LOG
When enabled, every tool call is recorded in a daily log file inside AUDIT_LOG_DIR. Each entry includes the timestamp, tool name, query or table, result, and execution time.
AUDIT_LOG=true
AUDIT_LOG_DIR=./logsLog format:
[2026-03-27T14:32:11Z] db_run_readonly | SELECT TOP 10 * FROM dbo.Orders | rows:10 | 45ms
[2026-03-27T14:32:20Z] db_run_readonly | SELECT * FROM dbo.Users | BLOCKED: table not allowed | 0msA new file is created each day: logs/audit-YYYY-MM-DD.log. Blocked queries are also logged.
Usage
Once the MCP is active, you can ask questions in natural language about your database. The agent will use the tools automatically to explore the schema and respond.
Test scripts
npm run test-connection # verify connectivity and list available tables
npm run test-schema # list all tables and views with column counts
node tests/test-table.js dbo.Employees # describe columns of a specific tableSecurity
Only
SELECTqueries are allowed. Blocked keywords:DROP,DELETE,UPDATE,INSERT,ALTER,TRUNCATE,CREATE,EXEC,EXECUTE,WAITFOR,XP_,SP_.SQL comments (
--and/* */) are stripped before validation.Tabs and newlines are normalized to prevent whitespace bypass attempts.
Multiple statements (
;) are not allowed.SELECT TOP Nis automatically injected if no row limit is present.ALLOWED_TABLESacts as a table whitelist (supports*wildcards), enforced indb_describe_schema,db_describe_tableanddb_run_readonly.
Tested attack vectors
Category | Examples | Result |
Direct writes |
| β Blocked |
Multiple statements |
| β Blocked |
System procedures |
| β Blocked |
DoS |
| β Blocked |
Whitespace bypass | tabs and newlines between keywords | β Blocked |
Comment bypass |
| β Blocked |
Valid queries |
| β Allowed |
Project structure
SQLQueryTools/
βββ mcp-server.js # Main MCP server
βββ mcp-sql-config.json # Reference MCP config for the client
βββ .env # Environment variables (do not version)
βββ env.example # Environment variables template
βββ package.json
βββ package-lock.json
βββ README.md # English documentation
βββ README.es.md # Spanish documentation
βββ tests/
βββ test-connection.js
βββ test-schema.js
βββ test-table.js # Usage: node tests/test-table.js dbo.Employees
βββ test-examples.jsTroubleshooting
Connection error:
Check that
SQL_SERVER,SQL_USERandSQL_PASSWORDin.envare correct.For cloud servers, try setting
SQL_ENCRYPT=true.If using a named instance, set
SQL_INSTANCE(e.g.SQLEXPRESS).Confirm that port 1433 is accessible from your network.
No tables shown in db_describe_schema:
Check
ALLOWED_TABLESin.env. If empty, all tables are shown; if set, verify the names/prefixes match.
MCP not appearing in Claude:
Verify the path in the config points correctly to
mcp-server.js.Restart Claude Desktop after any config change.
Check logs: Claude Desktop β Help β Open Logs Folder.
Author
--Pablon-- β github.com/negrip
Available Tools
6 toolsdb_describe_schemaA
Returns all available tables and views with their column count. Use this first to understand what data is available before writing queries. Results are cached to avoid repeated database calls.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It reveals that results are cached to avoid repeated database calls, a useful trait. However, it does not explicitly confirm read-only behavior, mention any permissions required, or describe potential side effects (though likely none). It adds some context but not comprehensive coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: what it returns, when to use it, and a note about caching. It is front-loaded with the core purpose and contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple, parameterless tool. The description conveys the return value ('tables and views with column count'), usage context ('use this first'), and a behavioral nuance (caching). Given the lack of output schema and no parameters, this is complete for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, and the input schema is empty. Per the rubric, 0 params earns a baseline of 4. The description appropriately avoids inventing parameter details and focuses on behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource: 'Returns all available tables and views with their column count.' This clearly differentiates it from siblings like db_list_databases (databases only) and db_describe_table (a single table), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Use this first to understand what data is available before writing queries' gives explicit when-to-use context. It implies this tool precedes query-writing tools but does not explicitly name alternatives or exclusions, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
db_describe_tableA
Returns full column details (name, data type, nullable) for a specific table or view. Use this when you need to know exact column names before writing a query.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Table or view name. Example: dbo.MyTable |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It transparently states the output ('Returns full column details') and the tool's name implies a read-only operation. It does not explicitly mention side effects or error conditions, but for a metadata descriptor, this is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The first sentence states the function and returned fields; the second sentence explains the typical use case. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a single simple parameter, no output schema, and a clear return type. The description fully covers what the tool does and when to use it. Nothing important is missing for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already defines the 'table' parameter with an example. The description adds little beyond stating 'specific table or view,' which does not significantly improve on the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns full column details (name, data type, nullable) for a specific table or view. It distinguishes itself from siblings like db_describe_schema (whole schema) and db_sample_data (data preview) by focusing on column metadata for one table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: 'Use this when you need to know exact column names before writing a query.' This tells the agent a concrete scenario, though it does not explicitly name alternatives or exclusions. Still, the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
db_list_databasesA
Returns the currently connected database name and status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It indicates the tool returns information and the qualifier 'currently connected' adds context about requiring an active connection. However, it does not explicitly state that the operation is read-only or describe potential error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the function and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless tool, the description provides basic information. However, it lacks detail about the 'status' return value and does not clarify the relationship to sibling tools like db_test_connection, leaving some ambiguity about its exact purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description adds no parameter-specific meaning. Per the guidelines, a zero-parameter tool receives a baseline score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the currently connected database name and status, which is specific and action-oriented. However, it does not explicitly distinguish itself from sibling tools like db_test_connection, which may also return status information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'currently connected' implies the tool is useful for checking the active database context, but there is no explicit guidance on when to use it versus alternatives. No exclusions or comparisons with sibling tools are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
db_run_readonlyA
Executes a SELECT query on SQL Server. Only read operations are allowed β write operations are blocked. TOP is automatically injected if no row limit is present. Use db_describe_schema and db_describe_table first if you are unsure about table or column names.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | SELECT SQL query to execute. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses two important behaviors: write operations are blocked, and TOP is automatically injected if no row limit is present. These are critical side effects that the agent would not otherwise know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with each adding value: the core action, behavioral constraint, and usage guidance. It is front-loaded and free of waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential facets for a generic query tool: functionality, constraints, side effects, and schema discovery fallback. Given there is no output schema, the absence of a return-value description is a minor gap, but the provided details are sufficiently complete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the query parameter (100% coverage). The description adds meaning by constraining the accepted query to read-only SELECTs and explaining the automatic TOP injection, which affects how the query parameter is interpreted and executed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource: 'Executes a SELECT query on SQL Server.' It also distinguishes itself from sibling tools by explicitly limiting to read-only SELECT commands, making it unique among schema exploration and test tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit advice to use db_describe_schema and db_describe_table first when unsure about names, and clarifies that write operations are blocked. It does not compare directly to db_sample_data, but the read-only SELECT context implies when to use this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
db_sample_dataA
Returns 5 sample rows from a table or view. Use this to understand the actual data format, values and patterns before writing a more specific query.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Table or view name. Example: dbo.MyTable |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that it returns exactly 5 rows and works on tables/views, but doesn't mention whether rows are randomly selected, deterministic, or if any side effects exist. Basic behavior is clear, but additional traits (e.g., row ordering, limits for small tables) are unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundant words. It front-loads the primary function ('Returns 5 sample rows') followed by practical usage guidance. Every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool without an output schema, the description is nearly complete: it defines the output (5 rows), the target (table/view), and the use case. It could optionally specify response format or ordering, but the essentials are well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the 'table' parameter with a description and example. The tool description adds no new parameter-specific meaning beyond restating 'table or view', so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Returns 5 sample rows from a table or view.' It uses a specific verb and resource, and distinguishes itself from siblings like db_describe_table (schema) and db_run_readonly (general queries) by focusing on sample data exploration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Use this to understand the actual data format, values and patterns before writing a more specific query.' This implies when to use it (exploratory phase) and suggests alternatives (later specific queries). It doesn't explicitly name sibling tools or state when not to use, but the guidance is strong enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
db_test_connectionA
Tests the connection to SQL Server and returns basic server information. Use this first to verify the server is reachable before running other tools.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden of transparency. It states the action ('Tests the connection') and the outcome ('returns basic server information'), adequately conveying a safe, read-only operation. It could explicitly mention that no data is modified, but the nature of a connection test strongly implies this, earning a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary verb and resource, and every word adds value. There is no fluff or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description covers the essential aspects: what it does and when to use it. It also positions it among sibling tools, making it contextually complete for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is trivially 100%. Per the rubric, the baseline for 0 parameters is 4. The description adds no parameter-specific information, but none is needed since there are no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Tests the connection to SQL Server and returns basic server information.' This is a specific verb-resource pair that distinguishes it from siblings like db_describe_schema and db_list_databases. The additional phrase 'Use this first' further differentiates its role as a prerequisite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage context: 'Use this first to verify the server is reachable before running other tools.' This gives clear when-to-use guidance and implies it should be the first tool executed, setting it apart from alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
6 tool updates
v1.0.0- First observed
db_describe_schema - First observed
db_describe_table - First observed
db_list_databases - First observed
db_run_readonly - First observed
db_sample_data - First observed
db_test_connection
TDQS
Each tool has a clearly distinct purpose: connection testing, schema overview, database info, table details, data sampling, and read-only query execution. The descriptions clarify any potential overlap between schema and table descriptions.
All tool names follow a consistent db_ prefix with snake_case verbs/nouns, such as test_connection, describe_schema, list_databases, describe_table, sample_data, and run_readonly. The naming pattern is uniform and predictable.
With 6 tools, the set is well-scoped for a SQL query server. Each tool covers a necessary step in the query workflow without redundancy or unnecessary additions.
The toolset covers the core read-only query workflow: connect, understand schema, sample data, and execute queries. Minor gaps like lack of multiple database listing or more advanced metadata are acceptable for the stated purpose.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
2,000+ MCP servers read at source level. Know what one does before you connect. Free, no key.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceRead-only SQL Server MCP server enabling safe database queries, table listing, and schema inspection with built-in security protections.MIT
- AlicenseAqualityBmaintenanceProduction-oriented MCP server for Microsoft SQL Server, enabling query execution, database discovery, schema introspection, and metadata inspection via MCP clients.64MIT
- FlicenseAqualityCmaintenanceA read-only MCP server for browsing and querying SQL Server databases, providing tools to list schemas, tables, describe columns, and execute safe SELECT queries with validated parameters.15-
- AlicenseBqualityCmaintenanceRead-only MCP server for exploring and analyzing SQL Server objects (tables, views, triggers, stored procedures) from Claude Code.8907MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/negrip/mcp-sqlserver-readonly'
If you have feedback or need assistance with the MCP directory API, please join our Discord server