QCDatabase.AI

QC Database MCP Server

A small program that lets an AI assistant (like Claude) do your everyday QC Database work for you — set the project you're working on, upload records, read what the AI pulled off a document, and find and close out the items still needed for a complete, traceable turnover package.

It runs on your own computer. Your AI assistant talks to it; it talks to QCDatabase.AI on your behalf, using your own login.

Built on the official Model Context Protocol Python library and the QC Database MCP specification — published at qcdatabase.ai/mcp_server_spec.md and kept in this repo as mcp_server_spec.md.

---

What you can ask your assistant to do

Once it's connected, you can talk to it in plain language. For example:

• *"Connect to QC Database."* → signs you in (opens your browser once).
• *"Work on the Riverside Unit 2 project."* → pins that project for the session.
• *"Upload this MTR to the Mill Test Reports folder."*
• *"What's still missing for turnover on this project?"*
• *"Show me the open reference requests assigned to me."*
• *"Find welds that failed X-ray near line 12."* → meaning-based (semantic) search across your project data, ranked by relevance.
• *"How do I create a test package in QC Database?"* → answers from the built-in QC Database user manual, so you can learn the app without leaving your assistant.
• *"Attach this photo to that weld."*
• *"Mark this inspection complete."* (it will remind you that the sign-off is recorded under your name — that's your call, not the AI's).

---

Before you start

You need Python 3.10 or newer on your computer.

• Windows: install from the Microsoft Store (search "Python") or from python.org/downloads. During the python.org install, tick "Add Python to PATH."
• Mac: brew install python or get it from python.org/downloads.

To check it's installed, open a terminal (PowerShell on Windows, Terminal on Mac) and run:

python --version

You should see Python 3.10 or higher. (On some Macs the command is python3.)

---

Install

From a terminal, in this folder:

pip install ".[runtime]"

That's it. This installs the server and a command called qcdatabase-mcp.

If pip isn't found, try python -m pip install ".[runtime]" (or python3 -m pip install ".[runtime]").

---

Install in Claude Desktop

Claude Desktop launches this server for you and shows its tools in your chats. Set it up once:

1. Install the Claude Desktop app

If you don't have it, download it from claude.ai/download and sign in.

2. Open the config file

In Claude Desktop:

1. Open Settings (Windows: menu ☰ → File → Settings; Mac: Claude → Settings).
2. Go to the Developer tab.
3. Click Edit Config.

This opens (and, if needed, creates) a file named claude_desktop_config.json. You can also open it directly:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

3. Add the QC Database server

Put this in the file. If the file already has other servers, just add the "qcdatabase" block inside the existing "mcpServers" section.

Windows:

{

"mcpServers": { "qcdatabase": { "command": "python", "args": ["-m", "qcdatabase_mcp"] } } }

Mac (Python is usually python3 there):

{

"mcpServers": { "qcdatabase": { "command": "python3", "args": ["-m", "qcdatabase_mcp"] } } }

Save the file.

If Claude can't start it (you see "python not found" or the server fails),

use the full path to Python instead of just "python". Find it by running

where python (Windows) or which python3 (Mac) in a terminal, then paste

that path as the "command". For example on Windows:

`json

{

"mcpServers": {

"qcdatabase": {

"command": "C:\\Users\\you\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",

"args": ["-m", "qcdatabase_mcp"]

}

}

}

`

(Use double backslashes \\ in Windows paths inside JSON.)

4. Restart Claude Desktop

Fully quit and reopen the app (on Windows, also close it from the system tray; on Mac, Quit with Cmd-Q — closing the window isn't enough). The new server only loads on a fresh start.

5. Confirm it loaded

Start a new chat and look for the tools/connector indicator (a slider or tool icon near the message box). Click it and you should see qcdatabase with its tools listed. If you don't, see Troubleshooting.

Then ask Claude to "connect to QC Database" to sign in — see below.

---

First time you use it

1. Sign in. Ask the assistant to *connect to QC Database* (the login tool). Your web browser opens; log in and pick which company workspace you want to connect. That choice locks the connection to that one organization. You only do this once — it's remembered.

1. Pick your project. Ask it to *work on* a project by name, or list your projects first. Almost every action happens "inside" a project, so the server asks you to choose one before it will do project work. You can switch projects any time.

1. Get to work. Upload documents and drawings, check what's missing for turnover, create and close reference requests, add notes and photos, and so on.

---

What it can do (tool groups)

• Session: login, logout, auth_status, whoami
• Find your way around: list_tenants, list_projects, set_project, get_active_project, list_project_members, list_lists, list_list_items, list_map_item_schemas, get_map_item_schema, list_document_folders, list_form_schemas
• Controlled-vocabulary lists: create_list_item, update_list_item, delete_list_item (a soft delete — the entry stops appearing in list reads but stays on record)
• Projects, jobs & packages: update_project, list_jobs, create_job, update_job, list_packages, create_package, update_package, list_line_specs, create_line_spec, update_line_spec (updates change only the fields you pass; name a field in clear to empty it)
• Upload records: upload_document, upload_document_version, download_document, upload_drawing, upload_large_format_drawing, upload_drawing_to_package, upload_drawing_version, upload_large_format_drawing_version, attach_photo
• Drawings: list_drawings (filter by type, status, job, package, or updated_since to see only drawings changed since a date-time), get_drawing (incl. pixel width/height — the HTML5-canvas coordinate space for map items), export_drawing, export_large_format_drawing, update_drawing (identifying metadata), move_drawing_to_package (existing drawing and destination in the active project; only changes package assignment, without uploading or duplicating)
• Fillable PDF forms: list_fillable_templates, get_fillable_template, download_fillable_template, submit_fillable_template
• Documents: list_documents (filter by folder, status, job, package, tags and metadata values), get_document_history, delete_document, bulk_delete_documents, list_deleted_documents, restore_document, bulk_restore_documents (deletes are soft: the document is archived and can be restored). download_document is the document export
• Structured data: get_document, set_document_extracted_data, list_map_items, get_map_item, create_map_item (place welds/flanges by pixel coordinates), update_map_item (rename, move, notes, assignee, working status), bulk_create_map_items, bulk_update_map_items (batch up to 500 items on one drawing/schema). Always call `list_map_item_schemas` first — see the CAD/PCF/.weldb note below
• Zipmaps (a whole mapped drawing in one upload): inspect_zipmap, upload_zipmap — see Zipmaps
• Repairs: list_repair_codes, add_map_item_repair
• Inspection forms & notes: list_form_submissions, create_form_submission, get_form_submission, update_form_submission, complete_form_submission, create_note, list_notes, resolve_note
• Photos: list_photos, attach_photo
• ITP & sign-offs (your call): list_itp_line_items, get_itp_line_item, create_itp_line_item, update_itp_line_item, mark_map_item_complete, mark_map_item_accepted, mark_itp_complete, mark_itp_accepted
• Quality-hold locks (witness/hold points — the user's call): list_lock_types (read only), list_locks, get_lock, add_lock (place a hold point — fit-up, tack-up, weld-cleanliness, FME, final-closure, boiler-tube FME sponge-in/sponge-out, etc. — on a map item or ITP line item so it can't be turned in until inspected), unlock_lock, assign_lock, delete_lock (withdraws a hold placed in error — a soft delete: kept in the audit trail, no longer holding the item; use unlock_lock for a hold that was actually satisfied). A lock is a construction quality gate, not a security control; place or clear one only at the explicit request of its owner/author or an authorized inspector. **Creating or editing lock *types* (the named hold definitions, and who may place/clear each) is intentionally not** exposed here — that permission-sensitive setup is done in the web app's Project Admin, and the assistant will point you there
• Turnover (the important part): list_reference_requests, create_reference_request, list_references, create_reference, turnover_report
• Shippers: list_shippers, get_shipper, list_shipper_line_items, list_shipper_types, list_shipper_locations, create_shipper, update_shipper, set_shipper_status, add_shipper_line_items, update_shipper_line_item, remove_shipper_line_item (a soft delete), delete_shipper (project admins only; a soft delete). Any status other than draft locks a shipper; unlocking, receiving and checklists stay in the web app. Needs the shippers:write scope: connections approved before it was added must reconnect (stdio: run login again) to get it
• Semantic search (meaning-based, ranked): semantic_search — natural-language search across the project's documents, drawings, large-format drawings, jobs, packages, list items, map items, form submissions, notes, and shippers
• How QC Database works: search_user_manual (ask "how do I…?" questions and read the product help articles), list_user_manual (browse the help contents)
• Trainings (playable trainings on redline.school): create_training, list_trainings, get_training, list_training_ideas, get_training_idea, get_training_policy (admins), upload_training_policy, get_training_authoring_guide, get_training_template, validate_training_bundle (free), upload_training_version (free; stores a private version only you can play), submit_training_review ($25 security review, needs confirm_charge), get_training_review and download_training_version (reviewed versions only, for co-developers). The local server zips a bundle folder itself and sends it straight to redline.school; on the hosted server, send a zip with begin_upload first. File contents never pass through the AI. These tools take an explicit scope rather than the active project. Connections approved before Trainings existed must re-approve to get trainings:read/trainings:write. Publishing, delisting and reassigning owners stay in the QC Database web app.
• Training compliance: assign_training and invite_users (admins; both preview until `co