Quickbase AI Toolkit

A small, safety-first toolkit for working with Quickbase using AI assistants (Claude and Claude Code). It pairs the QuickBaseClient wrapper with a few well-behaved scripts so your team can analyze data, export reports, draft formulas, and run bulk updates that are previewed and confirmed before they ever change anything.

Companion to the talk "Augmenting Quickbase with AI." See DEMO_RUNBOOK.md for the live-demo script and CLAUDE.md for the context Claude Code reads.

Two layers

• Analyze & report — Claude in chat via the kit's tiny read-only MCP (quickbase_mcp.py), which learns your app's schema and sample data on startup so you can ask in plain language — no terminal, no code, no field ids.
• Build & operate — Claude Code + this toolkit: read app structure, draft and test formulas, and run safe bulk updates from the command line.

Setup (about 5 minutes)

# 1. Get the kit
git clone https://github.com/josemsantiago/qb-ai-toolkit
cd qb-ai-toolkit

# 2. One command: installs deps, creates .env, wires up your AI tools
python setup_mcp.py

# 3. Edit .env (QB_REALM, QB_USER_TOKEN, QB_APP_ID) - then restart your AI app

# 4. Optional code-path check (read-only)
python scripts/query_preview.py --table bqXXXX --where "{3.GT.'0'}"

Not comfortable with a terminal? Double-click setup_mac.command (macOS) or setup_windows.bat (Windows) instead of typing the command. (Python must be installed first — the launcher points you to the download if it's missing.)

Chat with your data (no code) — the MCP

Want the no-code experience? One command installs everything and connects a read-only MCP server to Claude Desktop:

cp .env.example .env        # add your token
python setup_mcp.py         # installs deps + registers the MCP with Claude

Restart Claude Desktop, then just ask in plain language — "How many open invoices are overdue?" or "List my customers in Massachusetts." You don't need to know table names or field ids: on startup the MCP scans the app(s) you point it at (schemas, field names, choices, and sample values) and builds a local "memory" of your data, so Claude can map your wording to the right tables and fields. The MCP can only read — it lists, describes, queries, exports, and runs saved reports. Every write stays on the code path below.

• Which apps? Quickbase's API can't list every app a token can reach, so name the one(s) to scan with QB_APP_ID (or QB_APP_IDS=bxxxx,byyyy for several).
• Token access changed? Ask Claude to refresh access (the refresh_access tool) — it re-scans from scratch. The scan also re-runs on every startup. The memory files live in .qb_cache/ (git-ignored).
• Wide tables? Tune the scan in .env: QB_CATALOG_SAMPLE_ROWS (default 25) and QB_CATALOG_MAX_FIELDS (default 40).

Using Claude Code instead of Claude Desktop? setup_mcp.py prints the claude mcp add ... command to use.

Prefer manual installs? Clone the wrapper and install it yourself: git clone https://github.com/josemsantiago/QuickbaseClients.git && pip install -e ./QuickbaseClients/python -r requirements.txt

Works with your AI tool (macOS & Windows)

The MCP server is a standard stdio server, so it works with any MCP client — not just Claude. setup_mcp.py auto-configures each one it finds and prints the rest.

• Local (no hosting): Claude Desktop, Claude Code, Cursor, Windsurf, VS Code (GitHub Copilot, Agent mode), Gemini CLI, and other stdio clients. These are model-agnostic, so you can use GPT or Gemini through them and still use this server.
• ChatGPT: reaches servers only over HTTPS, so run it locally with python quickbase_mcp.py --http and expose the /mcp route through a tunnel (OpenAI Secure MCP Tunnel, ngrok, or cloudflared). Full steps in CLIENTS.md.

Run python setup_mcp.py --print for copy/paste configs, and see CLIENTS.md for exact file locations on macOS and Windows plus the ChatGPT steps.

Credentials — the right way

Your Quickbase user token goes in .env (which is git-ignored) and is read from the environment by config.py. It never gets pasted into a chat, committed, or hard-coded.

QB_REALM=yourcompany.quickbase.com
QB_USER_TOKEN=replace_with_your_user_token
QB_APP_ID=bxxxxxxxx

Habits that keep it safe:

• Least privilege — scope the token to only the app(s) you need.
• Never commit it — .env is already in .gitignore.
• Rotate & revoke — cycle tokens periodically; kill a leaked one immediately.
• Keep it out of chat — reference the variable name, not the value.

The golden rule for writes

Preview → Confirm → Commit. Run a read-only preview, eyeball the count and a sample, then commit in batches matching on Record ID# (so records are updated, never created). Bulk updates default to a dry run — real changes require --commit. Always test on a sandbox first.

What's inside

File	What it does
config.py	Builds the client from environment variables (single source of truth).
quickbase_mcp.py	Read-only MCP server — chat with your Quickbase in Claude (no code).
setup_mcp.py	One command: installs deps and registers the MCP with your AI tools.
setup_mac.command / setup_windows.bat	Double-click launchers (no terminal needed).
CLIENTS.md	Per-tool setup (Claude, Cursor, Windsurf, VS Code, Gemini, ChatGPT), macOS & Windows.
CLAUDE.md	Context Claude Code reads: how to connect, conventions, the golden rule.
scripts/query_preview.py	Read-only: how many records a query matches, plus a sample.
scripts/safe_mass_update.py	Set one field on matching records — preview → confirm → commit, dry-run by default.
scripts/export_report.py	Query a table and export to .xlsx with field-label headers.
scripts/describe_app.py	Print the app's tables, fields, and relationships.
formulas/	Authoritative, source-cited Quickbase formula reference: the language, the full function catalog, date/duration rules, and the Rich-Text/HTML + URL-button subset.
codepages/	How to build code pages (in-app HTML/JS widgets) and the authentication model (XML-as-the-logged-in-user by default; the elevated-token exception).
.claude/	Bundled Claude Code skills (quickbase-codepage, quickbase-formulas) and the quickbase-expert agent — auto-load when you open this folder in Claude Code (see below).
DEMO_RUNBOOK.md	Prep checklist and the three-act live-demo flow with fallbacks.
.env.example	Template for your credentials (copy to .env).
SECURITY.md	How the toolkit protects your token and data, and how to report an issue.
CONTRIBUTING.md	How to propose changes (and the safety rules that stay non-negotiable).
LICENSE	MIT.

Bundled Quickbase expertise for Claude Code (download → go)

Everything Claude Code needs to be a Quickbase expert ships inside this repo, so there is nothing extra to install. When you open the qb-ai-toolkit folder in Claude Code, it auto-loads:

• Skills (.claude/skills/)
  • quickbase-formulas — write, correct, and test formulas grounded in the cited reference (surfaces automatically when you ask for a formula; or type /quickbase-formulas).
  • quickbase-codepage — turn a Python script (or a request) into an in-app code-page widget that reads data live as the logged-in user, with no token in the page.
• Agent (.claude/agents/)
  • quickbase-expert — a specialist subagent for any Quickbase question (formulas, rich-text HTML, code pages, auth, safe writes) that grounds answers in formulas/ and codepages/ instead of guessing.

Just ask in plain language — "Write a Formula – Rich Text status badge," "Make this script a code page," "Why won't this formula compile?" — and the right skill/agent kicks in. The authoritative references it reads live in formulas/ and codepages/, so they're useful on their own even in Claude Desktop or any editor.

Use it in every project (optional): copy the skills and agent into your personal config — cp -R .claude/skills/* ~/.claude/skills/ && cp .claude/agents/*.md ~/.claude/agents/ — and they'll be available in Claude Code everywhere, not just this folder.

Quick examples

# Preview what a query matches (changes nothing)
python scripts/query_preview.py --table bqXXXX --where "{7.EX.'MA'}" --select 3 7 12

# Dry run a bulk update (changes nothing)
python scripts/safe_mass_update.py --table bqXXXX --where "{7.EX.'MA'}" --field 12 --value "NE"

# Apply it (asks you to type the match-count to confirm)
python scripts/safe_mass_update.py --table bqXXXX --where "{7.EX.'MA'}" --field 12 --value "NE" --commit

# Export a report
python scripts/export_report.py --table bqXXXX --where "{6.GT.'0'}" --select 3 6 7 12 --out open_items.xlsx

# Map the app's structure
python scripts/describe_app.py --app bxxxxxxx --fields

Notes

• The wrapper is zero-dependency (standard library). python-dotenv and openpyxl are optional extras used for .env auto-loading and Excel export.
• This toolkit is intentionally small and readable — extend it for your team.
• Not affiliated with or endorsed by Quickbase.

Security

Your token stays in .env (git-ignored), the MCP layer is read-only, and every write is previewed and confirmed before it runs. Details — and how to report a vulnerability privately — are in SECURITY.md.

Contributing

Small, focused pull requests are welcome. Please read CONTRIBUTING.md first — the safety rules (dry-run-by-default writes, read-only MCP, no committed secrets) are non-negotiable. main is protected, so changes land via pull request.

License

Released under the MIT License — © 2026 Jose Santiago Echevarria.

Author

Built by Jose Santiago Echevarria (@josemsantiago), companion to the talk "Augmenting Quickbase with AI." The QuickBaseClient wrapper it builds on lives at josemsantiago/QuickbaseClients.