kosminus/querywise-mcp

An **MCP server** (and a CLI) that lets an LLM query your databases in natural
language through a **business semantic layer** — glossary, metric definitions,
data dictionary, knowledge base, and example queries — grounded against your
real schema.
It's a refactor of QueryWise (a full-stack text-to-SQL app) into
a headless tool: no web UI, no Postgres requirement. The metadata store is an
embedded **SQLite + sqlite-vec** database, so the server runs from a single file.
Two ways to use it
1. **As an MCP server** — Claude (or any MCP client) calls the tools. The
recommended loop is:
get_semantic_context(connection, question) → the model writes a read-only
SELECT → run_sql(connection, sql). The client's own model does the
reasoning; the server provides grounded context + safe execution.
2. **As a CLI** — querywise ask " " runs the full
server-side NL→SQL pipeline (compose → validate → execute → interpret). This
path needs an LLM provider key (or local Ollama).
The semantic layer, connectors, and execution are shared by both.
Install
Configuration is via environment variables / .env (see .env.example). Zero
config works for keyword-only operation; add a key (or Ollama) to unlock
embeddings and the ask pipeline.
Quick start (zero external infra)
Run as an MCP server
Register with Claude
First make sure the store the server will read is initialized (and optionally seeded):
> **Use an absolute command path.** MCP clients launch the server with a minimal
> PATH, so the bare querywise-mcp often won't resolve. Point at the entry
> point inside your venv, e.g. /path/to/.venv/bin/querywise-mcp.
>
> **The server won't read your repo .env.** It runs from the client's working
> directory, so pass everything it needs (DATABASE_URL, provider keys, model)
> in the env block below.
**Claude Desktop** — edit
~/Library/Application Support/Claude/claude_desktop_config.json (macOS), then
fully quit and reopen Claude Desktop:
**Claude Code** — one command:
Note the **four slashes** in the SQLite URL — sqlite+aiosqlite:// (scheme) plus
the absolute path /Users/me/....
**Why DEFAULT_LLM_PROVIDER?** It's a *server* setting, not your chat model.
Claude is the client LLM — it calls the granular tools and writes the answer, so
it needs no provider config. The server only uses a provider for two things:
**embeddings** (semantic search over your metadata — optional; degrades to
keyword-only without one) and the all-in-one **ask/generate_sql** tools
(which run their own LLM). Set it to ollama for key-free local embeddings, or
to anthropic/openai (with the matching *_API_KEY in env) if you want to
call the server-side ask tool. Omit it entirely to run keyword-only.
MCP surface
**Tools** (25): list_connections, create_connection, test_connection,
introspect_connection, delete_connection, list_tables, describe_table,
get_semantic_context, run_sql, generate_sql, ask, query_history,
glossary/metric/dictionary/sample-query/knowledge management
(list_*/add_*/delete_*, plus add_knowledge_url).
**Query paths** — the four tools people mix up:
| Tool(s) | LLM key? | What it does |
|---|---|---|