Skip to main content
Glama
text2sql-mcp

text2sql-mcp

by 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]'

Related MCP server: MSSQL MCP

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

Available Tools

1 tool
queryA

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

    A4.7/5.0

    Scored across 1 tool

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables SQL agents to connect to any SQLAlchemy-supported database via MCP, providing read-only SQL querying, automatic table summarization, and column content search.
      4
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to connect to Microsoft SQL Server via the MCP protocol, supporting database schema queries, data reading, and arbitrary SQL execution.
      ISC
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to query a SQLite database using natural language through the Model Context Protocol (MCP). Includes security guardrails that block destructive SQL operations.
      -
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      42
      26 npm
      MIT