text2sql-mcp
Uses OpenAI's language model to convert natural language questions into SQL queries for execution on a connected database.
Connects to a PostgreSQL database to execute generated SQL queries and return results.
Connects to a SQLite database to execute generated SQL queries and return results.
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., "@text2sql-mcp What was the total sales last quarter?"
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.
text2sql-mcp
MCP server for text2sql-framework. Plugs into Claude Desktop, Cursor, Goose, or any other MCP-compatible assistant and lets it ask a SQL database questions in natural language.
The agent explores the schema, writes SQL, executes it against the real DB, and self-corrects on errors — no RAG layer, no schema descriptions, no pre-computed embeddings.
Install
Out of the box, text2sql-mcp supports SQLite + Anthropic:
pip install text2sql-mcp
# or
uvx text2sql-mcpFor other databases or LLM providers, install with the matching extra so the right driver gets installed:
You want… | Install command |
SQLite (default) |
|
Postgres |
|
MySQL |
|
Snowflake |
|
BigQuery |
|
OpenAI models | add |
Related MCP server: MSSQL MCP
Configure
Set environment variables in your MCP client config:
Variable | Required | Description |
| yes | SQLAlchemy URL, e.g. |
| yes | LLM provider key |
| no | LangChain model id (default: |
| no | Business rules / hints, e.g. "Revenue = net of refunds." |
| no | Path to a scenarios.md file for the agent's |
Claude Desktop / Cursor / generic MCP
{
"mcpServers": {
"text2sql": {
"command": "uvx",
"args": ["text2sql-mcp"],
"env": {
"TEXT2SQL_DATABASE_URL": "sqlite:///mydb.db",
"ANTHROPIC_API_KEY": "sk-ant-..."
}
}
}
}Goose CLI
goose configure
# Add Extension → Command-line Extension
# Name: text2sql
# Command: uvx text2sql-mcp
# Env: TEXT2SQL_DATABASE_URL, ANTHROPIC_API_KEYTools
query(question, max_rows=100)— ask the database a natural-language question. Returns{sql, data, error, row_count, tool_calls_made}.
How it works
Under the hood this is a thin wrapper around text2sql-framework, which uses LangChain Deep Agents to do iterative tool-calling against a single execute_sql tool. See the framework README for benchmarks (19/20 on Spider zero-shot across 80 tables) and architecture details.
License
MIT
Available Tools
1 toolqueryA
Ask the database a natural-language question.
The agent explores the schema, writes SQL, executes it, and self-corrects on errors before returning. Read-only — only SELECT-style statements.
Args:
question: The natural-language question, e.g. "top 5 customers by revenue".
max_rows: Cap on rows returned in data. Defaults to 100.
Returns:
dict with:
sql: the final verified SQL
data: list of row dicts (capped at max_rows)
error: error message if execution failed, else None
row_count: number of rows in data
tool_calls_made: how many SQL calls the agent made while exploring
Inputs: question (required), max_rows.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool, there is no possibility of confusion between overlapping functions. The tool's purpose is clearly defined for natural-language database queries, making selection trivial.
The single tool named 'query' is simple, intuitive, and uses a clear verb form. While there is no pattern to compare, the naming is unambiguous and follows common conventions for a query action.
The server has just one tool, which feels thin for a database interaction service. However, the tool is comprehensive and handles schema exploration, SQL generation, execution, and self-correction internally, so it may be sufficient for its narrow scope.
The tool covers the full natural-language query lifecycle: it interprets the question, writes SQL, executes it, and returns results with error handling. As a read-only query tool, it fully addresses the stated purpose without obvious gaps.
Maintenance
Related MCP Connectors
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables SQL agents to connect to any SQLAlchemy-supported database via MCP, providing read-only SQL querying, automatic table summarization, and column content search.4Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to connect to Microsoft SQL Server via the MCP protocol, supporting database schema queries, data reading, and arbitrary SQL execution.ISC
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to query a SQLite database using natural language through the Model Context Protocol (MCP). Includes security guardrails that block destructive SQL operations.-
- AlicenseBqualityCmaintenanceEnables AI assistants to connect to 17+ databases and query/analyze data using natural language via MCP and HTTP APIs, supporting platforms like Claude Desktop, Cursor, and VS Code.4226 npmMIT