text2sql-mcp
<!-- mcp-name: io.github.cpenniman12/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-mcp
For other databases or LLM providers, install with the matching extra so the right driver gets installed:
| You want… | Install command |
|---|---|
| SQLite (default) | uvx text2sql-mcp |
| Postgres | uvx 'text2sql-mcp[postgres]' |
| MySQL | uvx 'text2sql-mcp[mysql]' |
| Snowflake | uvx 'text2sql-mcp[snowflake]' |
| BigQuery | uvx 'text2sql-mcp[bigquery]' |
| OpenAI models | add openai, e.g. uvx 'text2sql-mcp[postgres,openai]' |
Configure
Set environment variables in your MCP client config:
| Variable | Required | Description |
|---|---|---|
TEXT2SQL_DATABASE_URL | yes | SQLAlchemy URL, e.g. sqlite:///mydb.db, postgresql://user:pass@host/db |
ANTHROPIC_API_KEY or OPENAI_API_KEY | yes | LLM provider key |
TEXT2SQL_MODEL | no | LangChain model id (default: anthropic:claude-sonnet-4-6) |
TEXT2SQL_INSTRUCTIONS | no | Business rules / hints, e.g. "Revenue = net of refunds." |
TEXT2SQL_EXAMPLES | no | Path to a scenarios.md file for the agent's lookup_example tool |
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_KEY
Tools
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