Metadata-Version: 2.4
Name: text2sql-mcp
Version: 0.1.0
Summary: MCP server for text2sql-framework. Lets any MCP-compatible assistant (Claude Desktop, Cursor, Goose, etc.) ask a SQL database questions in natural language.
Project-URL: Homepage, https://github.com/cpenniman12/text2sql-mcp
Project-URL: Repository, https://github.com/cpenniman12/text2sql-mcp
Project-URL: Bug Tracker, https://github.com/cpenniman12/text2sql-mcp/issues
Project-URL: text2sql-framework, https://github.com/cpenniman12/text2sql-framework
Author: Cooper Penniman
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,database,goose,llm,mcp,natural-language,sql,text-to-sql
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: langchain-anthropic>=0.3
Requires-Dist: mcp>=1.0
Requires-Dist: text2sql-framework>=0.3
Provides-Extra: openai
Requires-Dist: langchain-openai>=0.3; extra == 'openai'
Description-Content-Type: text/markdown

# text2sql-mcp

MCP server for [text2sql-framework](https://github.com/cpenniman12/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

```bash
pip install text2sql-mcp
# or
uvx text2sql-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

```json
{
  "mcpServers": {
    "text2sql": {
      "command": "uvx",
      "args": ["text2sql-mcp"],
      "env": {
        "TEXT2SQL_DATABASE_URL": "sqlite:///mydb.db",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}
```

### Goose CLI

```bash
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](https://github.com/cpenniman12/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
