Skip to main content

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:

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)

Source distribution for sqllens 0.0.2
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)

Table of built distributions (wheels) for sqllens 0.0.2
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.0.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page