QCDatabase.AI MCP server
Commit Nov 7, 2026Connects AI assistants to QCDatabase.AI to manage construction quality control, upload records, and prepare turnover packages.
Also known as ProcessQualitySolutions/qcdatabase_mcp, qcdatabase-mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Nov 7, 2026
- License
- MIT
What is QCDatabase.AI MCP?
QCDatabase.AI connects AI assistants to QCDatabase.AI to manage construction quality control, upload records, and prepare turnover packages.
Summary generated from the project's README
About QCDatabase.AI MCP server
QCDatabase.AI provides a bridge between AI assistants and the QCDatabase.AI platform to streamline construction quality control workflows. This MCP server runs locally on your computer using Python 3.10 or newer, allowing an AI client like Claude Desktop to act on your behalf using your existing credentials. By connecting through your web browser for authentication, the assistant can manage projects, upload technical records, and organize documentation.
Users can perform complex tasks such as uploading MTRs to specific folders, attaching photos to welds, and managing inspection forms. The server includes specialized tools for handling drawings, fillable PDF templates, and structured map items like flanges or welds. It also supports semantic search to find information across documents and notes using natural language. This setup is designed for construction professionals who need to track quality gates, manage turnover packages, and ensure all required documentation is complete and traceable.
What you can do with it
- 1Manage project documentationAsk your assistant to upload specific technical reports or drawings to designated project folders.
- 2Track turnover requirementsIdentify which items are still required to complete a traceable turnover package for a project.
- 3Perform semantic data searchesUse natural language to find specific construction defects or items within your project data.
- 4Access product documentationQuery the built-in user manual to learn how to perform specific actions within the web application.
Written from the project's README. Every use case is checked against a quote from it.
How to install QCDatabase.AI MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall QCDatabase.AI MCP in Claude Code
$ claude mcp add --transport http qcdatabase-mcp https://mcp.qcdatabase.ai/mcpInstall QCDatabase.AI MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"qcdatabase-mcp": {
"url": "https://mcp.qcdatabase.ai/mcp"
}
}
}Install QCDatabase.AI MCP in VS Code
.vscode/mcp.json
{
"servers": {
"qcdatabase-mcp": {
"type": "http",
"url": "https://mcp.qcdatabase.ai/mcp"
}
}
}Install QCDatabase.AI MCP in VS Code CLI
$ code --add-mcp '{"name":"qcdatabase-mcp","type":"http","url":"https://mcp.qcdatabase.ai/mcp"}'Install QCDatabase.AI MCP in Codex
$ codex mcp add qcdatabase-mcp --url https://mcp.qcdatabase.ai/mcpInstall QCDatabase.AI MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.qcdatabase-mcp] url = "https://mcp.qcdatabase.ai/mcp"
Install QCDatabase.AI MCP in Gemini CLI
$ gemini mcp add -s user --transport http qcdatabase-mcp https://mcp.qcdatabase.ai/mcpInstall QCDatabase.AI MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"qcdatabase-mcp": {
"url": "https://mcp.qcdatabase.ai/mcp",
"type": "http"
}
}
}Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableprocessqualitysolutions/qcdatabase_mcp is public and reachablegithub.com/processqualitysolutions/qcdatabase_mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-07github.com/processqualitysolutions/qcdatabase_mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubQC 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 pythonor 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
pipisn't found, trypython -m pip install ".[runtime]"(orpython3 -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:
- Open Settings (Windows: menu ☰ → File → Settings; Mac: Claude → Settings).
- Go to the Developer tab.
- 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 runningwhere python(Windows) orwhich python3(Mac) in a terminal, then paste that path as the"command". For example on Windows:{ "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
-
Sign in. Ask the assistant to connect to QC Database (the
logintool). 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. -
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.
-
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 inclearto empty it),attach_line_spec_documents,detach_line_spec_documents,generate_line_spec_requirements(an AI draft; save it withupdate_line_spec) - 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, orupdated_sinceto 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_documentis 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 calllist_map_item_schemasfirst — 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; useunlock_lockfor 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),reorder_shipper_line_items,delete_shipper(project admins only; a soft delete),unlock_shipper; checklists:confirm_shipper_checklist_item,unconfirm_shipper_checklist_item; receiving:receive_shipper_line_item,unreceive_shipper_line_item,add_shipper_line_item_note,remove_shipper_line_item_note,list_shipper_note_categories;audit_shipper,export_shipper_pdf; building a shipment:find_drawings_to_ship,get_drawing_bom_for_shipping,list_drawing_map_items_for_shipping,list_non_drawing_item_suggestions; settings (project admins):create_shipper_type,update_shipper_type,delete_shipper_type,create_shipper_location,update_shipper_location,delete_shipper_location. Any status other than draft locks a shipper until it is unlocked; checklists, receiving and notes work on locked shippers, with the web app's rules. Needs theshippers:writescope: connections approved before it was added must reconnect (stdio: runloginagain) 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, needsconfirm_charge),get_training_reviewanddownload_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 withbegin_uploadfirst. File contents never pass through the AI. These tools take an explicitscoperather than the active project. Connections approved before Trainings existed must re-approve to gettrainings:read/trainings:write. Publishing, delisting and reassigning owners stay in the QC Database web app. - Training compliance:
assign_trainingandinvite_users(admins; both preview untilconfirm=True, at most 200 people),list_assignments(the Training Matrix: completed / due / overdue / expired, and blocked / grace for required trainings),list_permission_requirements(which permissions need a current training; set only in the web app) andget_my_trainings(any member, one call: required and completed trainings, results, links, and gated permissions). Gated actions (accepting map items or ITP rows, lock actions, gated forms) can fail withtraining_required; the error names the training, its expiry and the link to take it. - Training competition:
get_training_leaderboard(any member who can play the game: ranked best scores by person, user type, project role or project, with your own rank) andget_engagement_report(admins: replays, voluntary plays, time trained, multiplayer, score improvement and trainings nobody replays, for the workspace, a project or one training). - Crew sessions (live multiplayer):
start_crew_session(a published multiplayer training; returns the join code, join link and QR link the crew scans to play together, optionally with an in-app invite to a project),list_crew_sessions,get_crew_session(who joined, teams, results as games finish),end_crew_sessionandinvite_project_to_crew_session. Starting, ending and inviting preview first and needconfirm=True. - Build service:
list_build_requests,get_build_requestand, for PQS staff,quote_build_request(price, $0 allowed, and description; previews first; emails both sides). A PQS Training Builder sees the builds assigned to them and builds each with the usual training tools (reviews included, no charge); a customer's admins see their requests and quotes. Requesting a quote, accepting the bid, accepting the training and change orders happen on the training page. - Crews:
list_crews(admins); assign a training to a crew withassign_trainingand{type: 'crew', crew_id}. Crews are edited in the web app. - Community forum (shared by all QC Database users):
list_forum_boards,list_forum_posts(filter by board, search, questions),get_forum_post,list_forum_replies,create_forum_postandreply_to_forum_post(optional image; on the hosted server, send it withbegin_uploadfirst). Posts are public to every company and are badged "via MCP" by QC Database, so the assistant shows you the text before posting. Connections approved before the Forum API existed must re-approve to getforum:read/forum:write. Moderation stays in the web app. - Utilities:
generate_qr_code
A companion to CAD, PCF, and .weldb systems
Map-item type definitions are read-only in MCP: discovery is available, but no create/edit/promote operation is exposed. Record edits and imports bind to existing schema IDs; archive schemas are not installed as new types.
List and document type creation/editing are permitted, but blocked by missing API write contracts. Document folder moves and package tags placed on LFDs are also API-blocked; moving a drawing to a package is not an LFD package tag. See the API handoff for the exact gaps. Hosted production needs a republish and refreshed client tool discovery before new tools appear; development verification alone does not update production.
This server is a natural partner to the systems that already describe your geometry — CAD/CAE exports, PCF piping files, and .weldb boilermaker replacement-panel files. Those sources carry most of what a good map item needs, so the assistant can turn them into accurate weld maps — if it follows two habits:
- Fetch the schema first. Always call
list_map_item_schemasbeforecreate_map_item/bulk_create_map_items. That picks the right schema and reveals its exact fields, so source values land where they belong instead of being guessed or free-texted:- PCF (piping) files carry most of what a pipe weld needs — joint type, material, weight/sch.
- .weldb files carry material, tube wall thickness, and the weld's rectangular position on the drawing — enough to build a weld map automatically.
- Match the source's geometry — point vs. rectangular welds. This is the big
data-quality lever. A PCF pipe weld is a single point weld (one x/y). A
.weldb weld has a rectangular position — give the second point
(
x_position_2/y_position_2) as the opposite corner so the extent is preserved. Collapsing a rectangular weld to a bare point (or spreading a point weld into a box) silently corrupts the map. Fetching the schema up front is what makes this distinction obvious before any items are placed.
Zipmaps: a whole mapped drawing in one upload
A zipmap is a plain zip that packages one drawing (a PNG, optionally the source single-page PDF) together with every map item already placed on it and the JSON Schemas that describe those item types. It is the "bring your own AI" hand-off: your model, CAD export, or takeoff tool produces the map; QC Database ingests it.
upload_zipmap replaces the old three-step dance (upload the drawing → wait →
bulk-create items against it) with one transactional request. The drawing, all
of its map items across every schema, and its extracted data are created together
— or nothing is. No server-side AI runs on it; the map is yours.
Ask for it in plain language: "upload this zipmap into the Unit 2 hydro package." Behind that, the assistant does three things first:
inspect_zipmap— looks inside without uploading: the drawing size, how many items of each type, the data fields those items use, and which types are not yet bound to a QC Database map item schema.list_map_item_schemas/get_map_item_schema— a zipmap names its types locally (weld,heat); QC Database identifies schemas by id. Any unbound type must be paired with the schema it belongs on (schema_ids={"weld": "<id>"}), and comparing the type's fields against the schema's fields is how that match is confirmed. Producers can skip this by writing the id into the archive'sschemata/<type>.schema.jsonup front.list_packages— the new drawing has to be filed somewhere, and the API requires a package id. Pick (orcreate_package) the scope package first.
Coordinates travel as pixels of the zipmap's PNG (top-left origin, y down) — exactly the space QC Database maps in — so nothing is rescaled or flipped. If the project uses per-schema auto-numbering, its labels win over the zipmap's item ids and the result reports each new item against the id it came from.
Re-sending a corrected map? mode="replace" first soft-deletes any live
drawing in that package with the same drawing number (retained in the audit trail,
gone from drawing lists, and its map items go with it) instead of leaving a
duplicate. The default, mode="append", always creates a new drawing.
Everything that can be checked locally is checked before the upload — a missing PNG, a type with no schema id, a coordinate outside the drawing, PDF-space coordinates that would misplace every item — so a bad map fails in a second with a list of what to fix, not after a multi-megabyte round trip.
Zipmaps are read from your own computer, so this works with the local (stdio) server. A hosted server never touches your disk (see Filesystem safety).
A note on sign-offs
Marking work complete or accepted is a buy-off — the system records it under your name and the current time. The assistant can do these for you, but every one of those tools tells you plainly that you are responsible for the action. The server never signs anything off silently. Treat those as your decisions, made with your go-ahead.
Privacy & safety
- The server runs locally and only talks to
https://qcdatabase.ai. - Your login is pinned to one organization (chosen at sign-in) and your session is pinned to one project — so the assistant can't reach into a different workspace or project by accident.
- The server only requests the permissions an everyday user needs; admin actions are out of scope by design.
- You can disconnect any connected app at any time from your QC Database account.
Your login is stored on your own computer in a per-user folder:
- Windows:
%LOCALAPPDATA%\qcdatabase-mcp\store.json - Mac:
~/Library/Application Support/qcdatabase-mcp/store.json - Linux:
~/.config/qcdatabase-mcp/store.json
Run the logout tool (or delete that file) to forget the login.
Filesystem safety (design invariant)
This is a hard rule the server must always uphold — for its own safety and for anyone contributing to this open-source repo:
- The server never modifies its own files. No tool can read from or write to
the server's whole installation — its own source, its dependencies
(
site-packages), the virtualenv, or (from a checkout) the repo root — whatever path it is given, so the assistant can never edit the server's or a dependency's code (no self-modification). Downloads also refuse to overwrite an existing file; choose a new path. - The server never touches its credential store beyond the token flow. No
tool can read or write the per-user config directory, so a token can never be
exfiltrated or overwritten through a tool, and it can never be committed to the
repo (it lives outside any checkout;
store.jsonis also.gitignored). - The only local files a tool ever touches are the user's own documents, and only in stdio mode — the upload tools read a file you point them at, and the download/export tools write to a path you choose. In hosted mode the server refuses all local filesystem access, because the disk is the server's, not yours (uploads/downloads there would need a client-side file channel instead).
These rules are enforced in code by _guard_local_path in server.py.
QCDatabase.AI MCP questions
How do I add QCDatabase.AI MCP to Claude Code?
Run claude mcp add --transport http qcdatabase-mcp https://mcp.qcdatabase.ai/mcp in your terminal. Add --scope user to make it available in every project.
How do I add QCDatabase.AI MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How do I sign in to the service?
You sign in by asking the assistant to 'connect to QC Database', which will open your web browser to authenticate and allow you to select your company workspace.
What are the system requirements for installation?
You need to have Python 3.10 or newer installed on your computer.