Click on "Deploy 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-mcp What are the top 5 products by sales this year?"
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.
An MCP server for read-only SQL Server access, plus a chat app (Express + React) that lets you ask questions about your databases in plain English.
Two things live in this repo:
An MCP server (src/index.ts) exposing query, list_tables, describe_table,
and list_databases tools — usable from Claude Desktop, Claude Code, or any other MCP client.
A standalone chat app (src/server.ts + web/) that drives that same MCP server with an LLM (Gemini, with free OpenRouter models as a fallback), so you can just type a question instead of writing SQL.
See ARCHITECTURE.md for how it's built and why (in particular, why it talks to SQL
Server via sqlcmd instead of a normal Node driver).
Node.js 18+ (20+ recommended)
sqlcmd on PATH — ships with the ODBC Driver 17 (or later) for SQL Server Client SDK
A SQL Server instance reachable from this machine (Shared Memory, Named Pipes, or TCP — sqlcmd handles whichever is available; no manual protocol configuration needed)
Related MCP server: mssql-mcp
Install dependencies:
npm install
cd web && npm install && cd ..Create a .env file in the project root:
SQL_SERVER=your-server-name
SQL_DATABASE=your-database-name
SQL_USER=sa
SQL_PASSWORD=your-password
GEMINI_API_KEY=your-gemini-api-keyGEMINI_API_KEY is required for the chat app (get one from Google AI Studio); the MCP server on its own doesn't need it.
Build:
npm run buildMCP server (for use with an MCP client like Claude Desktop):
npm start # runs the compiled dist/index.js
npm run dev # runs src/index.ts directly via tsx, no build stepChat app (two terminals):
npm run server # backend, http://localhost:3001
cd web && npm run dev # frontend, http://localhost:5173Quick connection sanity check:
npm run test-connectionTool | Description |
| Run a read-only |
| List all tables and views. |
| List a table's columns, types, and nullability. |
| List the configured database aliases (see below). |
Every tool takes an optional database argument to target a specific configured database.
By default there's one database, aliased app, configured via SQL_SERVER/SQL_DATABASE/SQL_USER/SQL_PASSWORD. To add more:
SQL_CONNECTIONS=idp,billing
SQL_IDP_SERVER=...
SQL_IDP_DATABASE=...
SQL_IDP_USER=...
SQL_IDP_PASSWORD=...
SQL_BILLING_SERVER=...
# etc.Each alias in SQL_CONNECTIONS needs its own SQL_<ALIAS>_SERVER / _DATABASE / _USER / _PASSWORD set. The chat UI's database picker and the list_databases tool pick these up automatically.
If GEMINI_API_KEY hits its rate limit, the chat backend can fall back to free models on
OpenRouter:
OPENROUTER_API_KEY=your-openrouter-key
# OPENROUTER_MODELS=openai/gpt-oss-20b:free,nvidia/nemotron-3-nano-30b-a3b:free,google/gemma-4-31b-it:freeLeaving OPENROUTER_API_KEY unset disables this fallback entirely — Gemini alone is used.
You can also override which Gemini models are tried, and in what order:
# GEMINI_MODELS=gemini-flash-latest,gemini-flash-lite-latest,gemini-2.5-flash-lite,gemini-pro-latestScript | What it does |
| Compile TypeScript ( |
| Run the compiled MCP server |
| Run the MCP server from source (no build) |
| Build, then run the chat backend on port 3001 |
| Verify the database connection and print the table list |
The query tool only allows SELECT/WITH statements — no INSERT/UPDATE/DELETE/DROP/etc., enforced in src/db.ts.
.env is gitignored. Never commit real credentials or API keys.
List the columns and types for a given table.
Inputs: tableName (required), database.
List the database aliases this server is configured to connect to.
Inputs: no named parameters.
List all tables and views in the database.
Inputs: database.
Run a read-only SELECT query against the database and return the results as rows.
Inputs: sql (required), database.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 4 tools
Each tool has a distinct purpose: list_tables returns the table list, describe_table provides schema for one table, list_databases shows configured connections, and query executes arbitrary SELECT statements. There's no overlap; an agent can easily determine which tool to use for a given task.
The first three tools follow a clear verb_noun pattern (list_tables, describe_table, list_databases). The fourth tool, 'query', is a single verb and doesn't fit the pattern cleanly, but it's still intuitive and not confusing.
With only 4 tools, the server is well-scoped for its purpose. Each tool is essential for database exploration and querying, and the count is within the ideal 3-15 range. The small number avoids redundancy and keeps the interface focused.
For a read-only SQL query server, the surface is complete: list databases to see connections, list tables, describe a table's schema, and run arbitrary SELECT queries. There are no obvious gaps for the stated purpose, and the read-only constraint is explicit.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Official Microsoft MCP Server to query Microsoft Entra data using natural language
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Hosted SQL Server MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
