SQL

SQL-MCP provides a dedicated server that bridges large language models with MySQL databases. It exposes metadata, safe read-only queries, and data sampling through a flexible MCP interface, enabling LLMs to explore and reason about your data securely and efficiently.

How to use

You interact with SQL-MCP through an MCP client that connects via either stdio (local, command-based workflow) or HTTP (remote service). In stdio mode, you run the MCP process locally and feed it through standard input/output. In HTTP mode, you run SQL-MCP as a standalone HTTP service and send requests to its endpoints. You can perform metadata queries, sample data, and read-only SQL operations while benefiting from built-in security bounds and caching.

How to install

Prerequisites: you need a recent version of Node.js installed if you plan to build or install via npm. You may also run a prebuilt image or use npm to install the MCP package globally.

npm i -g @polarisxb/sql-mcp

git clone https://github.com/polarisxb/sql-mcp.git
cd sql-mcp
npm ci
npm run build

Additional setup and usage notes

Choose your transport mode when starting the server. For local integration with tools that support command-based MCP, you can start the server in stdio mode. For a standalone service, start it in HTTP mode and connect clients via the provided HTTP API.

Example practical starts from the reference usage include starting via stdio with the MySQL configuration, or starting via HTTP to expose a REST-like endpoint.

Troubleshooting and tips

If you need to connect from an MCP inspector or a client, ensure the endpoint URL matches the mode you chose. For HTTP, the endpoint is typically http://127.0.0.1:3000/mcp. For stdio, verify that the command and arguments are correctly passed to the process and that environment variables are set as needed.

Enable verbose logs or adjust security settings to tailor rate limits, CORS, API keys, and timeouts to your environment. See the available environment variables for fine-grained control.

Notes

The server currently emphasizes MySQL support and provides a set of MCP tools to assist with query understanding, optimization, and correctness checks. When integrating with your tooling, keep in mind the safety boundaries and read-only restrictions to protect your data.

Available tools

explainQuery

Explain the parts of a query including involved tables, joins, filters, and potential risks.

optimizeQuery

Provide heuristic optimization suggestions such as index recommendations, rewrite ideas, and column pruning.

generateExamples

Generate common example queries for a given table with brief explanations.

fixQuery

Offer read-only equivalent rewrites or fixes based on error messages.

indexAdvisor

Offer index design advice focusing on filters, joins, sorts, and redundancy with evidence.

rewriteQuery

Provide a read-only rewrite draft, such as keyset pagination templates or avoiding SELECT *.

doctor

System health check covering connectivity, read-only availability, explain capability, and index statistics.