bluebonnet-sales
You can safely explore and query the Bluebonnet Outfitters sales database, run common sales reports, and preview/apply order status changes.
List tables and row counts, and describe table columns, types, and keys.
Run one read-only SQL
SELECTat a time, capped at 200 rows and stopped after 5 seconds.Get revenue, order count, and average order value for a date range, excluding cancelled orders.
Find top-spending customers, optionally within a date range and with a limit.
Find products at or below a stock threshold, lowest stock first.
Preview an order status change without
confirm=True, or apply it with confirmation; delivered/cancelled orders cannot be changed, and changes are logged to an audit log.
Provides safe, read-only querying and analysis of a SQLite business database, including table inspection, bounded SELECT queries, sales summaries, top-customer reports, low-stock checks, and audited order-status updates with preview and confirmation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bluebonnet-sales How did Q1 compare with Q4 on revenue and average order value?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Tables and their row counts |
| A table's columns, types and keys |
| One read-only |
| Revenue, orders and average order value between two dates |
| The biggest spenders, optionally in a date range |
| Products at or below a stock threshold |
| Changes an order's status: preview first, applied only with |
The summary tools cover the common questions with tested SQL. run_query handles everything else.
Related MCP server: text-to-sql-mcp
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,ATTACHorPRAGMAwrites, and no data-changing statements hidden inside aWITH.One statement at a time.
SELECT 1; DELETE FROM ordersis 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 installed.
git clone https://github.com/hostedinthebarn/claude-sql-demo.git
cd claude-sql-demo
uv run pytest # optional: 21 testsThen 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.jsonWindows:
%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:
{
"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
SELECTrights, so the database enforces read-only as well as the serverkeep the row cap and the time limit (
statement_timeoutin 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.
The code is MIT licensed. The name "claude-sql-demo" and any logos aren't covered by the licence.
Available Tools
7 toolsdescribe_tableBRead-only
Show a table's columns, types and keys.
Inputs: table (required). Returns: result
list_tablesARead-only
List the tables in the database with their row counts.
Inputs: no named parameters. Returns: result
low_stockARead-only
Products with stock at or below a threshold, lowest first.
Inputs: threshold. Returns: result
run_queryARead-only
Run one read-only SQL SELECT and return up to 200 rows.
Anything that would change data, attach another database or change settings is refused. Queries are stopped after 5 seconds.
Inputs: sql (required).
sales_summaryARead-only
Revenue, order count and average order value between two dates (YYYY-MM-DD, inclusive).
Cancelled orders are left out.
Inputs: end (required), start (required).
top_customersBRead-only
The customers who spent the most, optionally between two dates (YYYY-MM-DD).
Inputs: end, limit, start. Returns: result
update_order_statusAIdempotent
Change an order's status. Without confirm=True this only previews the change.
Delivered and cancelled orders are final and can't be changed.
Inputs: status (required), order_id (required), confirm.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Read-only answers from your business database, with the SQL and conditions behind each number.
131Read and write Sage Intacct from Claude or ChatGPT. Write tools are flagged for approval.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables Claude to answer questions about a small business's own data by providing predefined sales, customer, refund, and inventory tools, plus a guarded read-only SQL query tool with audit logging.6MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude to translate natural-language business questions into safe, read-only SQL queries by exposing tools for listing tables, inspecting schemas, and executing row-capped SELECT statements against PostgreSQL.MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude to query and safely write to a Postgres database, driven entirely by one policy file with read-only access by default, column-precise PII masking, and an append-only audit log. SQL is parsed and validated before execution, writes use parameterized queries with dry-run/confirm and transactions, and every call is rate-limited and audited so destructive or exfiltrating requests are refused.MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude or any MCP-capable assistant to explore and query a small business's sales, payments, invoices, and expenses through read-only SQL tools, while personal-data columns and write operations are refused by the database policy.MIT