bluebonnet-sales
# Claude SQL demo
An MCP server that lets Claude answer questions from a business's SQL database, safely.
It runs against **Bluebonnet Outfitters**, a made-up outdoor-gear shop: 60 customers, 16 products and a year of orders in a local SQLite file. Ask Claude things like:
- "How did Q1 compare with Q4 on revenue and average order value?"
- "Who are our top 5 customers this year, and where are they?"
- "What's about to run out of stock?"
- "Which products sell together most often?"
- "Mark order 510 as shipped."
The first four are read-only. The last one changes data, so Claude shows you a preview first and only applies it when you say yes.
## The tools
| Tool | What it does |
|---|---|
| `list_tables` | Tables and their row counts |
| `describe_table` | A table's columns, types and keys |
| `run_query` | One read-only `SELECT`, up to 200 rows |
| `sales_summary` | Revenue, orders and average order value between two dates |
| `top_customers` | The biggest spenders, optionally in a date range |
| `low_stock` | Products at or below a stock threshold |
| `update_order_status` | Changes an order's status: preview first, applied only with `confirm=True`, logged to `audit_log` |
The summary tools cover the common questions with tested SQL. `run_query` handles everything else.
## Guard rails
Giving an AI a database connection is only sensible with limits. This server enforces them in code, not in the prompt:
- **Read-only by construction.** Queries run on a connection that opens the file read-only, and an SQLite authorizer refuses anything that isn't a read: no `INSERT`, `UPDATE`, `DELETE`, `DROP`, `ATTACH` or `PRAGMA` writes, and no data-changing statements hidden inside a `WITH`.
- **One statement at a time.** `SELECT 1; DELETE FROM orders` is refused.
- **Bounded.** At most 200 rows come back, and a query is stopped after 5 seconds.
- **Writes need a yes.** The only tool that changes data previews first, refuses changes to final orders, and writes an audit record.
- **Tool hints.** Every tool tells Claude whether it's read-only, so the app can ask before using the one that isn't.
The tests try each of these and check the database is unchanged afterwards.
## Run it with Claude Desktop
You need [uv](https://docs.astral.sh/uv/) installed.
```sh
git clone https://github.com/hostedinthebarn/claude-sql-demo.git
cd claude-sql-demo
uv run pytest # optional: 21 tests
```
Then add the server to Claude Desktop's config file. Quit Claude Desktop first (⌘Q on a Mac), because it rewrites the file while it runs and can drop your change. The file is at:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
Add an `mcpServers` section at the top level, next to anything already in the file. Use the full path to `uv` (run `which uv`, or `where uv` on Windows), because Desktop doesn't see your shell's PATH, and the full path to the folder you cloned:
```json
{
"mcpServers": {
"bluebonnet-sales": {
"command": "/full/path/to/uv",
"args": ["run", "--directory", "/full/path/to/claude-sql-demo", "claude-sql-demo"]
}
}
}
```
Start Claude Desktop again. If the tools don't appear, the log is `mcp-server-bluebonnet-sales.log` in `~/Library/Logs/Claude/` (Windows: `%APPDATA%\Claude\logs\`). The database is created on first use, at `bluebonnet.db` in the project folder. Set `BLUEBONNET_DB` to put it somewhere else. To start again from fresh data, delete the file.
## Using it with a real database
The demo uses SQLite so it runs with one command. For SQL Server, Postgres or MySQL, the shape stays the same:
- connect with a database user that only has `SELECT` rights, so the database enforces read-only as well as the server
- keep the row cap and the time limit (`statement_timeout` in Postgres, a query timeout in SQL Server)
- write tools that do one business action each, with a preview and an audit trail, instead of letting the model write SQL that changes data
- keep credentials in environment variables or the OS keychain, never in the config file you share
## Licence
MIT. See [LICENSE](LICENSE).
The code is MIT licensed. The name "claude-sql-demo" and any logos aren't covered by the licence.
TDQS
Scored across 7 tools
The schema tools (list_tables, describe_table, run_query) and the canned reports (sales_summary, top_customers, low_stock) each target a clearly different question, and update_order_status is the only mutating tool. The one soft overlap is that run_query could reproduce any of the report tools, so an agent must decide between a prebuilt report and ad-hoc SQL, but the descriptions make the intended choice reasonably clear.
All names are consistently snake_case and readable. The verb_noun pattern holds for list_tables, describe_table, run_query and update_order_status, but the three report tools (sales_summary, top_customers, low_stock) drop the verb and use noun phrases, a minor deviation from an otherwise predictable convention.
Seven tools is well-scoped for a sales-database server: three discovery/query primitives, three focused reports, and one guarded write. Nothing feels redundant or padded, and there is no obvious missing operation forcing extra tools.
The surface covers schema discovery, arbitrary read queries, common sales analytics, inventory alerts, and a confirmed order-status update. There is no detail-level order/customer lookup or any create/delete path, but run_query serves as an escape hatch for read gaps, so the omissions are workaround-able rather than dead ends.