text2sql-mcp

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