SQL Lens
Natural-language SQL analytics over MCP. Connect any MCP-aware AI assistant — Cursor, Claude Desktop, Windsurf, custom client — to a database and ask questions in plain English.
Status: Pre-alpha. APIs and config will change before
0.1.0.
What it does
A standalone MCP server that wraps a natural-language SQL agent + a vector memory store. It exposes two tools:
| Tool | What it does |
|---|---|
query_database(question) |
Translates the question to SQL, runs it, returns a Markdown table. |
list_data_sources() |
Describes the configured database (name, dialect, read-only state). |
One database per running instance. Read-only by default — generated SQL is parsed with sqlglot and rejected if it isn't a SELECT. ChromaDB stores per-question memory locally so the agent learns from corrections.
Quick start (60 seconds, with the bundled SQLite Chinook DB)
git clone https://github.com/The01Geek/sqllens.git
cd sqllens
pip install -e ".[all]"
export SQLLENS_LLM__API_KEY=sk-ant-...
sqllens serve -c examples/sqlite-demo/sqllens.toml
The server is now live on stdio. Point an MCP client at the process and ask: "How many albums did AC/DC release?"
Prefer HTTP? Edit the config:
[server]
transport = "http"
host = "127.0.0.1"
port = 8765
sqllens serve starts uvicorn at http://127.0.0.1:8765/mcp/. Both /mcp and /mcp/ work; / redirects to the canonical form.
Configure
sqllens init writes a starter sqllens.toml. Every field can be overridden by environment variables — nested fields use double-underscore:
export SQLLENS_DATABASE__URL="postgresql://user:pw@host/db"
export SQLLENS_LLM__API_KEY="sk-ant-..."
export SQLLENS_AUTH__MODE="bearer"
export SQLLENS_AUTH__BEARER_TOKEN="abc-123"
Env vars beat TOML — the convention containerized deploys expect.
Database URLs
| Dialect | Example |
|---|---|
| SQLite | sqlite:///./demo.db |
| Postgres | postgresql://user:pw@host:5432/dbname |
| MySQL | mysql+pymysql://user:pw@host:3306/dbname |
Auth modes
| Mode | When to use |
|---|---|
none |
Loopback only. The default for sqllens init. |
bearer |
Single shared token. Set auth.bearer_token in TOML or SQLLENS_AUTH__BEARER_TOKEN in env. |
jwt |
Scaffolded — not implemented yet. The verifier interface is locked; the implementation lands in a follow-up. Don't deploy with this mode. |
Wire up an IDE
Drop one of these into the appropriate config file:
- Cursor (
~/.cursor/mcp.json) — seeexamples/mcp-clients/cursor.json - Claude Desktop (
~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS) — seeexamples/mcp-clients/claude_desktop.json - Windsurf — see
examples/mcp-clients/windsurf.json - stdio variant (no HTTP server, IDE launches the process) — see
examples/mcp-clients/stdio-cursor.json
For interactive testing, use the official MCP Inspector:
npx @modelcontextprotocol/inspector
Set transport to Streamable HTTP, URL to http://localhost:8765/mcp/, add an Authorization: Bearer … header if you've enabled bearer auth, click Connect.
Local development
git clone https://github.com/The01Geek/sqllens.git
cd sqllens
pip install -e ".[dev,all]"
ruff check .
pytest -q
The integration test suite spins up a real uvicorn server and exercises the full Streamable HTTP wire protocol end-to-end. No real LLM calls are made — query_database is gated behind a separate, opt-in test that requires a live Anthropic key.
Project structure
sqllens/
├── src/sqllens/
│ ├── cli.py # Typer entrypoint: version | init | validate | serve
│ ├── config.py # pydantic-settings: TOML + SQLLENS_ env vars
│ ├── server.py # Dispatch to stdio or HTTP transport
│ ├── transport/http.py # Streamable HTTP + auth middleware + path normalizer
│ ├── tools/ # MCP tool implementations
│ ├── agent/ # NL-to-SQL agent + framework
│ ├── connectors/ # Reserved for SQLAlchemy-backed adapters (Phase 3)
│ ├── auth/ # none | bearer | jwt
│ └── safety/ # Read-only SQL guard
├── examples/
│ ├── sqlite-demo/ # Bundled Chinook DB + working config
│ └── mcp-clients/ # Drop-in config snippets per IDE
└── tests/
├── unit/ # Config, auth, safety
└── integration/ # Live HTTP transport with mcp SDK client
Install
Three install paths, all produced by the same release pipeline:
| Path | Command | Use when |
|---|---|---|
| PyPI | pip install sqllens[all] then sqllens serve |
You're a Python user or running on a server. |
| Docker | docker run -p 8765:8765 -e SQLLENS_LLM__API_KEY=… -e SQLLENS_DATABASE__URL=… ghcr.io/the01geek/sqllens:latest |
You don't want a Python install on the host. Multi-arch (amd64 + arm64), signed with cosign, SBOM attached. |
| MCPB | Drag the .mcpb for your platform onto Claude Desktop. |
You only use Claude Desktop and want a one-click install. See mcpb/README.md. |
Roadmap
- Phase 1 — Spike: agent lifted, scaffold in place, SQLite Chinook demo runs locally.
- Phase 2 — Auth (none + bearer), SQL safety guard, Streamable HTTP transport, integration tests.
- Phase 3 — Distribution: PyPI workflow, multi-arch Docker image, MCPB bundle, real-DB connector tests.
- Phase 4 — JWT verifier (JWKS + shared-secret), permission scopes, integration with Guidoo.
Contributing
Open from day 1. See CONTRIBUTING.md. Bug reports and feature requests via the issue templates.
License
Apache 2.0. See NOTICE for copyright and LICENSES/ for third-party attributions.
Metadata
Release files for sqllens 0.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sqllens-0.0.2.tar.gz | 522.7 kB | With provenance | Details for sqllens-0.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sqllens-0.0.2-py3-none-any.whl | Python 3 | none | any | Details for sqllens-0.0.2-py3-none-any.whl |
Total release size: 677.0 kB
Release files / sqllens-0.0.2.tar.gz
| Download URL | sqllens-0.0.2.tar.gz |
|---|---|
| Size | 522.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c2f33a099200115fb2cc7823b5c239538034271fdb9f3998e486a7f7c5c2d77a
|
|
BLAKE2b-256 checksum How to use checksums |
f49bb8aefb9a5cf3f4c983cfe3b337fc52895bafa36a1f851f2ca77d9acb496a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 28, 2026.
Transparency logRelease files / sqllens-0.0.2-py3-none-any.whl
| Download URL | sqllens-0.0.2-py3-none-any.whl |
|---|---|
| Size | 154.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
03c2d2203009c6489e3dd6310250f615223971d631229d04b08ca0e72015085a
|
|
BLAKE2b-256 checksum How to use checksums |
cc5349231c36db40cb316841c9aa20bc2114af3e380f96a2afe2ac00dfa5b6e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 28, 2026.
Transparency logSecurity for sqllens 0.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for sqllens-0.0.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 28, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.