QIMA API MCP

Latest Update Time: 2026-07-07 00:00:00

QIMA API MCP turns any Model Context Protocol client (Cursor, Claude Desktop, and other AI assistants) into a hands-on assistant for the QIMA Public API. Instead of reading the docs and hand-writing requests, you can just ask your AI assistant to explore endpoints, explain fields, generate request scripts, and even call the APIs for you.

It runs locally on your machine and talks to the same QIMA Public API documented on this portal.

Download

⬇ Download QIMA API MCP (.zip)

The archive is self-contained: it bundles the server code plus a copy of the API specification and guides, so it works offline for exploration and scripting. The source also lives in the developer portal repository under src/mcp.

What it can do

Capability	Description
Explore APIs	List modules, search endpoints, and describe an endpoint's parameters, request-body fields, and responses.
Explain fields	Look up what any request/response field means — its type, whether it is required, and its allowed values.
Generate scripts	Produce ready-to-run `curl` or Python snippets for any endpoint, including the authentication step.
Authenticate & call	Obtain a short-lived token from `POST /auth/v2/token` using your credentials, then call other endpoints on your behalf.

Requirements

Python 3.10 or newer
A QIMA customer account, plus your Ai-Api-Access-Token (from QIMA sales or IT support)
Recommended: uv — then there is nothing to install manually

Installation

Option A — with `uv` (recommended, zero setup)

Unzip the download. That's it — no virtualenv, no pip install. The server declares its own dependencies, and uv installs them automatically the first time your AI client launches it. Just point your client at server.py with the uv command (see the configuration below).

Install uv once if you don't already have it:

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Option B — with a virtualenv + pip

cd qima-api-mcp
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Configuration

The server is configured entirely through environment variables set in your MCP client. Exploration tools need no configuration; only authenticate and call_api require credentials.

Variable	Required for	Default	Description
`QIMA_ACCESS_TOKEN`	auth / calls	–	Your `Ai-Api-Access-Token`, provided by QIMA.
`QIMA_ACCOUNT`	auth / calls	–	Your QIMA login / username.
`QIMA_PASSWORD`	auth / calls	–	Your password (plain text or a 32-char MD5 hash). Plain text is hashed automatically.
`QIMA_API_BASE_URL`	–	`https://ppapi.qima.com`	API host. Override for production.
`QIMA_REFERER`	–	`https://preprodmy.qima.com/`	`Referer` header value (must stay constant across a session).
`QIMA_USER_TYPE`	–	`client`	`client` or `employee`.

Security: your password and access token are never embedded in generated scripts or tool output. The access token is masked, and scripts read secrets from the environment at runtime.

Cursor / Claude Desktop (recommended, with `uv`)

Add the server to your MCP config — Cursor's ~/.cursor/mcp.json or Claude Desktop's claude_desktop_config.json — pointing at where you unzipped the download. With uv, the command is simply uv run server.py:

{
  "mcpServers": {
    "qima-api": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/qima-api-mcp/server.py"],
      "env": {
        "QIMA_ACCESS_TOKEN": "<your-ai-api-access-token>",
        "QIMA_ACCOUNT": "<your-username>",
        "QIMA_PASSWORD": "<your-password>"
      }
    }
  }
}

Without `uv` (virtualenv + pip)

If you used Option B, point command at that virtualenv's Python instead:

{
  "mcpServers": {
    "qima-api": {
      "command": "/absolute/path/to/qima-api-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/qima-api-mcp/server.py"],
      "env": {
        "QIMA_ACCESS_TOKEN": "<your-ai-api-access-token>",
        "QIMA_ACCOUNT": "<your-username>",
        "QIMA_PASSWORD": "<your-password>"
      }
    }
  }
}

After saving, reload your client's MCP servers. The qima-api server should appear with its tools available.

Available tools

Tool	Purpose
`list_api_categories`	List API modules and endpoint counts.
`list_apis`	List endpoints (optionally filtered by category).
`search_apis`	Keyword search across endpoints.
`get_api_details`	Full parameters / request-body fields / responses for one endpoint.
`explain_field`	Explain a field's meaning, type, required flag, and enum values.
`read_api_guide`	Return a human-written guide (e.g. `getting-started`).
`generate_request_script`	Generate a `curl` or `python` script for an endpoint.
`get_config_status`	Show configured values (masked) and auth readiness.
`authenticate`	Call `POST /auth/v2/token` and cache the session token.
`call_api`	Directly call any endpoint with the right headers injected.

Example prompts

Once connected, try asking your AI assistant:

"List the Inspection endpoints and explain how to create a booking."
"What does announcementType mean in the audit order create request?"
"Generate a Python script to search inspection orders."
"Authenticate and get the details of a specific order for my user."

How authentication works

The server sends account + MD5(password) + userType with the Ai-Api-Access-Token and Referer headers to POST /auth/v2/token.
The returned token, userId, refreshKey, and validBefore are cached in memory. Business calls add the Ai-User-Id and Authorization: Bearer <token> headers automatically.
The token is re-fetched automatically when it is missing or near expiry.

Getting Started Guide — Authentication and your first API call
Module Overview — Overview of all QIMA Public API modules
API Reference — Interactive endpoint explorer for all Public APIs

Documents