Skip to main content
Glama
bluebonnet-sales

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.

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, 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 installed.

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:

{
  "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.

The code is MIT licensed. The name "claude-sql-demo" and any logos aren't covered by the licence.

Available Tools

7 tools
describe_tableB
Read-only

Show a table's columns, types and keys.

Inputs: table (required). Returns: result

list_tablesA
Read-only

List the tables in the database with their row counts.

Inputs: no named parameters. Returns: result

low_stockA
Read-only

Products with stock at or below a threshold, lowest first.

Inputs: threshold. Returns: result

run_queryA
Read-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_summaryA
Read-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_customersB
Read-only

The customers who spent the most, optionally between two dates (YYYY-MM-DD).

Inputs: end, limit, start. Returns: result

update_order_statusA
Idempotent

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

    A3.7/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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