TrimbleX9-mcp
This server lets an AI agent inspect a Trimble X9 scanner and download scan data, but it is read-only apart from local file downloads.
Check scanner status, including battery, storage, levelling, Wi-Fi config with secrets masked, and errors.
List projects, scans, scan modes, and running or queued tasks.
Wait for a running scan/task to finish, with progress and timeout controls.
Get metadata for one point-cloud file.
Download a scan’s
.tzfpoint-cloud file into the configured download directory.Download a scan’s preview JPEG.
Convert a box on a downloaded preview into area-scan angles for use by an actuating client.
It cannot start scans, create/delete projects or scans, cancel tasks, or otherwise move the instrument with the tools shown.
Provides tools for interacting with a Trimble X9 terrestrial laser scanner over its local HTTP/REST API, enabling agents to query scanner status, list projects and scans, read scan-mode menus and errors, retrieve scan-file metadata, download point clouds and preview images, and optionally create projects, launch scans, and delete scans or projects.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TrimbleX9-mcp What's the scanner status, and are there any errors?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TrimbleX9-mcp
This MCP server is how you ask your favorite chatbot to work with the scanner. Give an AI agent the objective for the job, and with trimble-x9-bridge it can plan each scanner setup from the last scan, tie each new station into the ones before it, and get real measurements back from the point cloud, like window sizes and wall heights.
An MCP server for the Trimble X9 terrestrial laser scanner. It gives an AI agent tools to read the scanner's status, list projects and scans, read the scan-mode menu, download point-cloud files and previews, and, behind an explicit opt-in, create projects and start full-dome or area scans.
It runs in one of two modes:
Direct mode talks to the scanner's own local HTTP/REST API (
/api/v1) over its USB or Wi-Fi link. The safety checks run in this server.Bridge mode talks to a separate x9 bridge service that sits next to the scanner and enforces the rules (approvals, battery, busy scanner, echo checks) for every client. The tools are thin calls to the bridge's API.
What the agent gets back is something it can look at. The minimap of a
19-station colour scan of an administration building, redrawn by
scanner_minimap after every station:
And where to set up next: scanner_plan_station picks the spot from the
station's points, and scanner_propose_station shows the person the spot,
the landmark beside it and a tripod drawn its real size there, with its
shadow on the ground:
Tested with Claude Opus 5.5 and Grok 4.6 as the model in the chat: given the same plan, both put the tripod on the same spot of pavement.
Interoperability project: written from scratch against the instrument's network API, with behavior verified on a live instrument. No vendor code, firmware or vendor documentation is included or redistributed. How the API knowledge was obtained is recorded in PROVENANCE.md. Independent project, not affiliated with or endorsed by Trimble Inc.; "Trimble" and "X9" are trademarks of their respective owners.
I built this clean-room from how the scanner behaves and the data it returns. It uses no Trimble source code, internal documents, or confidential information, including anything from my past employment at Trimble.
Contents: Install · Modes · Configuration · Tools · Safety · Errors · Client configuration · Compatibility · Tests · full tool reference in docs/tools.md.
Install
Python 3.10 or later. Install from the GitHub release tag; this provides the
console script trimblex9-mcp, which speaks MCP over stdio.
pip install "git+https://github.com/northidaholabs/TrimbleX9-mcp@v0.17.0"
# or, isolated:
pipx install "git+https://github.com/northidaholabs/TrimbleX9-mcp@v0.17.0"
# or run without installing:
uvx --from "git+https://github.com/northidaholabs/TrimbleX9-mcp@v0.17.0" trimblex9-mcp
# no git on the host (e.g. a minimal Raspberry Pi image):
pip install https://github.com/northidaholabs/TrimbleX9-mcp/archive/refs/tags/v0.17.0.tar.gzDependencies: mcp and httpx (see Compatibility).
On a Raspberry Pi without internet
A field Pi is often on the scanner's Wi-Fi, with no internet. Build a wheelhouse on a machine that has internet, for the Pi's Python (Raspberry Pi OS trixie: CPython 3.13, aarch64), copy it over and install from it:
# on a machine with internet
tag=v0.17.0
pip wheel --no-deps -w wheelhouse "git+https://github.com/northidaholabs/TrimbleX9-mcp@$tag"
pip download -d wheelhouse --only-binary=:all: --platform manylinux2014_aarch64 \
--python-version 3.13 --implementation cp "mcp>=1.7,<3" "httpx>=0.27"
curl -L -o wheelhouse/trimblex9-mcp-auto \
https://raw.githubusercontent.com/northidaholabs/TrimbleX9-mcp/$tag/extras/trimblex9-mcp-auto
scp -r wheelhouse <pi>:
# on the Pi
python3 -m venv ~/x9-bridge/.venv
~/x9-bridge/.venv/bin/pip install --no-index --find-links ~/wheelhouse trimblex9-mcp
install -D -m 0755 ~/wheelhouse/trimblex9-mcp-auto ~/x9-bridge/bin/trimblex9-mcp-autoThe launcher (extras/trimblex9-mcp-auto, from v0.12.1) starts the server for
a field kit; see
On a field Pi, through the bridge.
trimblex9-mcp is meant to be started by an MCP client, not run by hand; on a
terminal it just waits for MCP messages on stdin.
Related MCP server: Bambuddy MCP Server
Modes
The mode is chosen once, at start-up, from the environment:
|
| Result |
unset or empty | (ignored) | Direct mode: talks to the scanner at |
set | set | Bridge mode: talks to the bridge at |
set | unset or empty | Exits at start-up with |
The two modes expose different tool sets (see Tools). In bridge mode
SCANNER_BASE and SCANNER_ALLOW_ACTUATION are ignored: the bridge decides
what a token may do.
Direct mode
Run the server on the host the scanner is connected to (by USB, or on the
scanner's Wi-Fi). Out of the box the server is read-only: tools that move
the instrument, fire its laser or delete data are not registered at all
unless SCANNER_ALLOW_ACTUATION is set. With it set, the server validates
every scan request locally, refuses to start a scan or delete data while the
scanner is busy,
and cancels any scan the instrument did not accept exactly as sent.
Bridge mode
The bridge is the only thing that talks to the scanner. This server sends
each call to the bridge's HTTP API with a bearer token the bridge issued,
usually with role agent. With an agent token, a scan waits in
awaiting_approval until a person approves it in the bridge app, unless the
person granted a set of scans in advance. Approval, grant and delete tools
are deliberately absent from this server. Bridge mode adds exports to
PLY/LAS, previews returned as images, aiming, recipes and a field log.
The bridge itself is a separate service and is not part of this repository.
Configuration
All configuration is through environment variables.
Variable | Mode | Default | Effect |
| direct |
| Base URL of the scanner's HTTP API. The default is the scanner over its USB network link; use its Wi-Fi address (e.g. |
| direct | unset (off) |
|
| both |
| Directory that download tools write into and that |
| bridge | unset | Bridge API base, e.g. |
| bridge | unset | Bearer token issued by the bridge, sent as |
| bridge | unset | An |
| bridge | 8 | How long the permission given in the chat lasts (up to 20 scans) |
Timeouts are fixed in the code, not configurable:
Request | Direct mode | Bridge mode |
Ordinary API calls | 15 s (5 s to connect) | 30 s (5 s to connect) |
File downloads (streamed) | 600 s (5 s to connect) | 600 s (5 s to connect) |
| — | 120 s (5 s to connect) |
The long-running waits (scanner_wait_for_scan, scanner_wait_for_job) poll
and take their own timeout_s argument (1 to 7200 s, default 900).
Tools
A summary; parameters, return values and rules for each tool are in docs/tools.md.
"Read" tools only query. "Local write" tools write files into
SCANNER_DOWNLOAD_DIR but do not change the scanner. "Actuating" tools move
the instrument or fire its laser. "Destructive" tools stop work or delete
data. Each tool carries matching MCP annotations (readOnlyHint,
destructiveHint).
Direct mode, always registered
Tool | Kind | What it does |
| read | Battery, AC, levelling, storage, IMU, laser pointer, Wi-Fi config (secrets masked), errors |
| read | List projects |
| read | List scans as compact records |
| read | The scan-mode menu (range, points, size, time, spacing, rate) |
| read | Current error list |
| read | Running or queued tasks with percent complete; empty means idle |
| read | Wait until no task is running, reporting progress |
| read | Metadata of one point-cloud file |
| local write | Download a scan's |
| local write | Download a scan's preview JPEG |
| read (local only) | Turn a box on a downloaded preview into area-scan angles |
Direct mode, only with SCANNER_ALLOW_ACTUATION
Tool | Kind | What it does |
| write | Create a project |
| actuating | Start a full-dome scan |
| actuating | Start a scan of an angular window |
| destructive | Stop a running task |
| destructive | Delete a scan and its file, by scanUUID; refused while busy |
| destructive | Delete a project and its scans, by projectUUID; refused while busy |
A typical direct-mode scan: scanner_scan_modes → scanner_projects (or
scanner_create_project) → scanner_launch_scan → scanner_wait_for_scan →
scanner_scans → scanner_download_scanfile.
Bridge mode
Tool | Kind | What it does |
| read | Bridge and scanner state: connection, busy, battery, storage, levelling, moved-since-last-scan, queue length |
| read | Scan modes with range, angular step, point count and timings |
| read | Projects with scan counts |
| write | Create a project by name |
| read | Scans, newest first, optionally for one project |
| read | One scan's record |
| actuating (queued; usually needs approval) | Queue a full-dome or area scan |
| read | One job's state and progress |
| read | Wait for a job, returning early if it needs approval |
| destructive | Cancel a job; a running scan is stopped |
| read | A scan's preview, returned as an image the agent can see |
| read | Turn a box on a preview into an area-scan window |
| write (on the bridge) | Decode a scan to levelled PLY or LAS |
| read | An export's point count, bounds and checks |
| local write | Download an export file |
| local write | Download a scan's raw |
| read | Installed recipes |
| read | One recipe's inputs and steps |
| write (may lead to scans) | Start running a recipe |
| read | A run's state and steps |
| write | Complete a person step of a run |
| write | Measure a window opening in a scan on the bridge (bridge 0.4.0+) |
| read | A measurement's values, checks and evidence image |
| read | Standing permissions to scan: project, expiry, scans left, who gave them, and the run they cover |
| read | Computes where to set up next from a full dome's points: up to three spots on open ground a person can walk to, a real step out, seeing the most of what this station couldn't (behind and beside a named subject, if given), each with its preview pixel and a landmark beside it (bridge 0.14.0+) |
| write | Marks where to set up next on the station's preview: the tripod, the one landmark the person walks past, and a sentence naming it (no left, right or compass words). The bridge refuses a proposal that breaks that, shows it in its web UI and returns the picture (bridge 0.8.0+) |
| write | Sets what the job is for (the person's goal, kind, done-when criteria) and its first ledger targets (bridge 0.8.0+) |
| read | The mission, its state and its ledger |
| read | The project's stations in one frame (registered by the bridge after each full dome), the walls found, and the plan picture (bridge 0.9.0+) |
| read | Where registration runs: the laptop workers connected, or the Pi; how to start a worker on the laptop. Ask the person once per laptop (bridge 0.10.0+) |
| write | Asks the person, in the chat, to confirm a run's sign-off step (or to correct the numbers); relayed with |
| read | The job so far as a simple line map: walls, numbered stations (amber when not trusted), wall targets; redrawn after every station (bridge 0.11.0+) |
| read | How much of a wall face the registered stations saw: share of its length, spacing, stations, unseen stretches (bridge 0.9.0+) |
| write | Adds or updates ledger targets: open, covered (by stations), measured (with a measurement), declined (with a reason). A wall target can carry a question ( |
| write | Asks a question target of the point cloud now (bridge 0.15.0+): |
| write (asks the person) | Says the job is done (refused while a target is open) and asks the person to sign it off in the chat, or relays their words |
| write | Saves the project to a folder on the laptop: scan files, each station's points in the project frame (COPC), registration, mission, and a manifest with checksums. The sign-off starts one by itself; this saves again (bridge 0.18.0+) |
| read | Where the project's data landed: the laptop, the folder, when, and each station (bridge 0.18.0+) |
| write | Loads a door and window schedule, an inspection and test plan's spreadsheet (bridge 0.20.0+), or a list, as the job's mission: one line per mark or row (bridge 0.19.0+) |
| read | The list line by line: requirement, whether it is sorted, its grade and question, status, a sorting proposed and waiting (bridge 0.19.0+; |
| write (asks the person) | Proposes each line's grade of evidence, question and tolerance arithmetic, asks the person, then sorts exactly what they were shown with the person's token (bridge 0.20.0+) |
| read | What each line of the list came to: status, conformance, evidence (bridge 0.19.0+) |
| write | Asks the person, then binds list lines to the wall they are on (bridge 0.19.0+) |
| write | Counts the openings on each bound wall, with sizes, a picture per wall, and proposed matches to the schedule (bridge 0.19.0+) |
| write | Asks the person which opening is which schedule line, then judges each line against its tolerance (bridge 0.19.0+) |
| read | A scan's point spacing and coverage plan (seen, shadows), with the plan image (bridge 0.6.0+) |
| write | Propose a person step's answer (e.g. the box around the window) for a person to confirm (bridge 0.3.0+) |
| destructive | Stop a run and any scan in flight |
| read | The field log |
| write | Add a note to the field log |
Prompt (bridge mode)
Prompt | Arguments | What it does |
|
| Runs a site visit toward one goal: asks once about processing on the laptop, asks which one when the view shows more than one thing the job could mean, sets the mission, scans station by station with the minimap and registration, proposes each next station by the landmark the person walks past, and ends with the one sign-off |
|
| Fetches the recipe from the bridge and returns step-by-step instructions for walking it with the person: which inputs to ask for, then |
Direct mode has no prompts.
The person, in the chat
The person says what they want and signs off the result; the agent does the rest. Two moments need the person, and both are asked in the chat itself, through MCP elicitation, where the answer comes from the person and not from the model:
Permission for the visit.
scanner_start_runandscanner_start_scancheck for a grant in the project. Without one it asks once: "Let the agent scan in "" for the next 8 hours (up to 20 scans)?". Yes creates the grant withSCANNER_PERSON_TOKEN; no starts nothing. Later runs in the visit ask nothing.The sign-off.
scanner_sign_off(run_id, summary)asks about the bridge's proposal at the run's sign-off step: confirm it, or change the numbers, which the form shows prefilled with the proposal. The agent shows the evidence image in the chat first. This is the run's one person intervention.
Clients (October 2026): the Claude Code CLI shows elicitation from 2.1.76.
The Claude desktop app's Code tab declares it but closes the question without
showing it (seen 2026-10-21), and the desktop chat and claude.ai don't support
it. A Claude Code Elicitation hook can answer without showing a dialog;
don't configure one for this server.
When the chat can't ask (or closes the question unshown), the tool says so
and tells the agent to ask the person in plain chat, then call again with
person_said = the person's exact words (and, for the sign-off, corrections
for numbers they changed). That is weaker: the model carries the person's
answer. So the bridge records it: the grant's note reads "relayed by the
agent: "…"", the sign-off's input has confirmed_via, and the run counts it in
interventions.relayed. Questions answered in a dialog are noted "asked in
the chat".
Missions: a defined "done"
The person's sentence ("scan the exterior of the house", "measure all the
windows") becomes the project's mission: their goal, a kind, and done-when
criteria the agent writes, concrete enough to check. The agent keeps a ledger
of targets (each facade, each window) as it works: open, covered by named
stations, measured, or declined with a reason. It chooses the next station for
what is still open, and scanner_ready_to_leave is refused while anything is.
Then the person signs the job off once, in the chat (or relayed), and the
mission is done. The survey_mission prompt runs the whole visit.
From bridge 0.9.0 the bridge registers every full dome into one project
frame by itself. Facade targets then name their wall (wall_id from
scanner_registration), and the bridge covers them from the geometry: a
wall seen over 80% of its length is covered, with the stations that saw it,
and covered is refused while less is seen.
Safety
For agents, in short:
Permission: scans run under a grant the person gives once per visit, in the chat. Never use the operator (person) token yourself; the server uses it only after the person said yes.
Secrets: never print, paste or log tokens or the scanner's Wi-Fi passphrase. Keep tokens in files (
~/x9-bridge/*.token), not in client settings: prefer the launcher over--env SCANNER_BRIDGE_TOKEN=…, which stores the token in the client's config.The laser pointer (the scanner's own
laser-pointerAPI, not exposed by these tools): only with the person at the scanner and having said so, and never without explicit angles aimed at the floor.
Read-only by default (direct mode)
Without SCANNER_ALLOW_ACTUATION the actuating and destructive tools are not
registered, so a client sees a read-only server and cannot call them. Starting
a scan moves the instrument and fires its laser; make sure the instrument is
safely set up before enabling them.
Launch checks (direct mode)
The scanner answers HTTP 202 even to a scan request it cannot parse, and then
runs a default full-dome scan. It also ignores projectUUID unless
projectName matches too. So scanner_launch_scan and
scanner_launch_area_scan, in this order:
Validate the angles (area scan):
delta_hain (0, 2π],0 ≤ start_va,0 < delta_va,start_va + delta_va ≤ π.start_hais wrapped into [0, 2π).Refuse while busy: if any task is running or queued, they fail with
instrument is busy: <type> <taskUUID> (<state>)…and send nothing. Another client, or another agent, may be driving the instrument.Check the project:
project_uuidmust parse as a UUID, and a project with that name and that UUID must exist.Check the mode:
scan_modemust be one of the names inscanner_scan_modes.Send, then compare the echo: the instrument echoes the request it accepted. Every field sent (
scanMode,projectName,projectUUID,scanType,fastMode,colorMode, and the four angles for an area scan) must come back unchanged (floats to within 1e-9). On any mismatch the server cancels the task at once and returnsinstrument did not accept the request as sent (sent vs echoed: …); cancelled its task (HTTP <status>).
scanner_delete_scan and scanner_delete_project refuse in the same way
while any task is running or queued: a scan being filed renumbers the scan and
project lists that the delete verification relies on, and deleting the project
a scan is writing into is never wanted. scanner_create_project does not
check, since a new project does not touch the running task. scanner_cancel_task
is meant for a running task, so it does not check either.
Delete by UUID, verified (direct mode)
Scan and project ids on the scanner are list positions and are renumbered
after every delete. The delete tools therefore take the stable scanUUID or
projectUUID, look up its current id immediately before deleting, and read
the list again afterwards. The delete is reported as done only if that UUID is
gone and the list is exactly one shorter; otherwise the tool fails with
delete of <uuid> not confirmed; re-check <kind> before retrying.
Downloads stay in one directory (both modes)
Download tools write only inside SCANNER_DOWNLOAD_DIR:
filenamemust be a plain name: it starts with a letter or digit, then up to 127 more letters, digits,.,_or-. No directories, no.., no leading dot.The resolved path must sit directly in the download directory, so a symlink that points elsewhere is refused.
An existing file is kept unless
overwrite=true.Data streams into
<name>.partand is renamed into place only when complete; the.partfile is removed on failure.
scanner_preview_to_angles reads files only from the same directory, by plain
name.
Secrets masked (direct mode)
The scanner returns its Wi-Fi passphrase in plain text in its status.
scanner_status replaces every non-empty string value whose key ends in
key, psk, passphrase, password, secret or token (any case) with
***, at any depth. Booleans such as isFactoryKey are kept. Only
scanner_status is masked. In bridge mode the bridge decides what its status
contains.
Bridge mode
The bridge enforces approvals, battery limits, a busy scanner, a scanner that
moved since the reference scan, and request echo checks, for every client.
This server adds only input shape checks (for example, all four window angles
or none) and the download-directory rules above. Ids (scan_id, job_id,
export_id, run_id, recipe_id) are sent as single URL path segments with
every reserved character escaped, and an empty id, . or .. is refused, so
an id cannot reach a different bridge endpoint. Whether projects can be
created while the scanner is busy is the bridge's decision; bridge mode has no
delete tools.
Errors
Tool failures are raised as MCP tool errors (ToolError), so the message text
reaches the client on both mcp 1.x and mcp 2.x (mcp 2.x hides the text of
other exceptions). The messages are:
Situation | Message |
Scanner answered with an HTTP error (direct) |
|
Scanner unreachable (direct) |
|
Bridge refused (bridge) |
|
Bridge answered an error without a problem body (not JSON, or JSON without |
|
Scanner or bridge answered success with a body that is not JSON |
|
Truncated or malformed |
|
Any other bad value in a reply or file |
|
Bridge unreachable (bridge) |
|
Validation, busy, echo, delete and file-name checks | A plain sentence saying what was wrong and what to do, e.g. |
Client configuration
On a field Pi, through the bridge (recommended)
The usual setup: the scanner talks to
trimble-x9-bridge on a
Raspberry Pi by the tripod (its ops/README.md builds the Pi), this server runs
on the same Pi, and the agent on the laptop starts it over ssh. The launcher
extras/trimblex9-mcp-auto (installed at ~/x9-bridge/bin/) runs bridge mode
with the bridge's agent token from ~/x9-bridge/agent.token, and passes the
person's token from ~/x9-bridge/operator.token as SCANNER_PERSON_TOKEN, used
only after the person says yes in the chat. With an ssh alias x9-bridge for
the Pi (key login, no prompts):
claude mcp add -s user x9-bridge -- ssh -o BatchMode=yes x9-bridge 'X9_MCP_MODE=bridge ~/x9-bridge/bin/trimblex9-mcp-auto'Quote the remote command, so ~ is the Pi's home, not the laptop's.
Check: the client lists the scanner_* tools, and scanner_status shows the
bridge and the scanner. X9_MCP_MODE=direct starts the same server in direct
mode for diagnostics; it stays read-only while the bridge runs.
Claude Code
Direct mode, read-only:
claude mcp add trimblex9 -- trimblex9-mcpDirect mode with actuation and custom paths:
claude mcp add trimblex9 \
--env SCANNER_ALLOW_ACTUATION=1 \
--env SCANNER_BASE=http://192.168.43.1:34567/api/v1 \
--env SCANNER_DOWNLOAD_DIR=$HOME/scans \
-- trimblex9-mcpWithout installing first:
claude mcp add trimblex9 -- uvx --from "git+https://github.com/northidaholabs/TrimbleX9-mcp@v0.17.0" trimblex9-mcpBridge mode:
claude mcp add trimblex9 \
--env SCANNER_BRIDGE_URL=http://bridge.local:8795/v1 \
--env SCANNER_BRIDGE_TOKEN=<agent token> \
-- trimblex9-mcpGeneric mcpServers JSON
For clients configured with an mcpServers object (Claude Desktop, many
others):
{
"mcpServers": {
"trimblex9": {
"command": "trimblex9-mcp",
"env": {
"SCANNER_BASE": "http://192.168.42.1:34567/api/v1",
"SCANNER_DOWNLOAD_DIR": "/home/user/scanner-downloads"
}
}
}
}Add "SCANNER_ALLOW_ACTUATION": "1" to env to enable actuation. For bridge
mode, set SCANNER_BRIDGE_URL and SCANNER_BRIDGE_TOKEN instead. If
trimblex9-mcp is not on the client's PATH, give its full path (for a
virtualenv, <venv>/bin/trimblex9-mcp).
On a remote host over SSH (e.g. a Raspberry Pi by the scanner)
The scanner is usually reached from a small computer on site, not from the
machine running the agent. Install the server on that host and let the client
start it over SSH; MCP's stdio transport passes through ssh unchanged. With
the bridge on that host, use the launcher as in
On a field Pi, through the bridge.
Without a bridge (direct mode):
# on the agent's machine
claude mcp add trimblex9 -- ssh -T pi@scanner-pi.local \
'SCANNER_DOWNLOAD_DIR=$HOME/scanner-downloads ~/x9-bridge/.venv/bin/trimblex9-mcp'{
"mcpServers": {
"trimblex9": {
"command": "ssh",
"args": ["-T", "pi@scanner-pi.local",
"SCANNER_ALLOW_ACTUATION=1 ~/x9-bridge/.venv/bin/trimblex9-mcp"]
}
}
}Notes:
Set the environment variables in the remote command, as above. A client's
--env/"env"applies to the localsshprocess and is not forwarded to the remote host.Use key-based login with no password prompt (
ssh -Tand no TTY); the client cannot answer prompts.On current Raspberry Pi OS and Debian the system
piprefuses to install into the system Python; usepipxor a virtualenv, and point the command at thattrimblex9-mcp.Downloaded files land on the remote host, in its
SCANNER_DOWNLOAD_DIR.Use the full path to
trimblex9-mcpif the remote non-interactive shell'sPATHdoes not include it.
Compatibility
Item | Supported |
Python | 3.10 and later |
| 1.x ( |
| 0.27 and later |
OS | Linux and macOS (anything that can reach the scanner's network link) |
Transport | stdio |
CI runs the tests on Python 3.10 with mcp 1.7 (the floor; pinned with
pydantic<2.14, because mcp 1.7 imports a pydantic internal that 2.14
removed), on Python 3.10 with the newest mcp 1.x, and on Python 3.13 with
mcp 2.x. If you must stay on mcp 1.7, keep pydantic below 2.14. The tools use tool annotations, which FastMCP accepts from
mcp 1.7, so the requirement is mcp>=1.7,<3.
Tests
python3 -m venv .venv
.venv/bin/pip install -e . pytest
.venv/bin/pytest -qTest file | Needs | Covers |
| nothing (starts in-process stubs of the scanner and bridge APIs) | Direct mode with actuation on: delete by UUID across renumbering, local launch validation, area-scan echo check, cancel on a mismatched echo, |
|
| Bridge mode against a real bridge and scanner simulator: tool list has no approve/grant/delete tools, approval flow and progress, bridge error codes, an escaped id that would otherwise reach another endpoint, recipe prompt and run, field log |
| nothing (scripts an in-process bridge stub) | The bridge-mode tools against the stub: the requests each sends, how it reads the replies, and the error paths, including asking the person, older bridges, lists and counting, and the save |
| an mcp SDK with elicitation (skipped on 1.7) | Every question the server asks the person is a flat form of primitive fields that chat apps accept |
Bridge-mode tests are skipped unless these are set:
Variable | Effect |
| Directory holding the |
| Directory of dome/area |
X9_BRIDGE_BIN=/path/to/bridge/target/release pytest -q tests/test_bridge_mode.pyDevelopment
.venv/bin/trimblex9-mcp # run over stdio
python scanner_mcp.py # same, from a checkoutscanner_mcp.py is direct mode and the entry point; scanner_bridge.py is
bridge mode and reuses the download-path helpers from scanner_mcp.py.
License
This project is open source under AGPL-3.0-or-later. See LICENSE.
A commercial license is available for companies that want to embed or host it without AGPL obligations. See northidaholabs.com/license.
Releases published before this change keep the license they were published under.
Available Tools
11 toolsscanner_download_previewB
Download a scan's panoramic preview JPEG into the server's download directory (default name 'scan--preview.jpg'); same rules as scanner_download_scanfile.
Inputs: scan_file_id (required), filename, overwrite.
scanner_download_scanfileA
Download a scan's point-cloud file into the server's download directory
(SCANNER_DOWNLOAD_DIR). filename is a plain name (default
'scan-.tzf'); paths are rejected. Existing files are kept unless
overwrite is true. Streams the full file; returns bytes and path.
Inputs: scan_file_id (required), filename, overwrite.
scanner_errorsARead-only
Get the instrument's current error list (type, errorLevel, description).
Inputs: no named parameters.
scanner_preview_to_anglesARead-only
Convert a box drawn on a scan's preview JPEG into instrument angles for
scanner_launch_area_scan. Both files must already be in the download
directory (scanner_download_scanfile + scanner_download_preview of the same
scan, taken from the station the instrument is still standing on).
(x0, y0)-(x1, y1) are preview pixel corners, y down; if x1 < x0 the box
wraps across the panorama seam. margin_deg pads every side.
Returns start_ha/delta_ha/start_va/delta_va in radians (VA from zenith).
Inputs: x0 (required), x1 (required), y0 (required), y1 (required), +3 more.
scanner_projectsARead-only
List all projects on the instrument (id, projectName, projectUUID, nextProjectScanID).
Inputs: no named parameters.
scanner_scanfile_infoBRead-only
Get metadata for one point-cloud file: file path, size, point count, and whether it has been downloaded.
Inputs: scan_file_id (required).
scanner_scan_modesARead-only
List the available scan modes (the density/range/time menu): mode name, range (m), point count, file size, scan time (s), spacing, and rate. Use these names when starting a scan.
Inputs: no named parameters.
scanner_scansARead-only
List all scans as compact records (id, scanUUID, scanMode, points, file path, and the project folder the scan belongs to). Ids are list positions and change when scans are deleted; scanUUID is stable.
Inputs: no named parameters.
scanner_statusARead-only
Get the instrument's current status: battery, AC state, leveling, on-board storage, IMU, laser-pointer, WiFi config (passphrase masked), and the active error list.
Inputs: no named parameters.
scanner_tasksARead-only
List running or queued tasks (e.g. a scan in progress) with their state and percent complete (0-100). An empty list means the instrument is idle.
Inputs: no named parameters.
scanner_wait_for_scanARead-only
Wait until no task is running (use after scanner_launch_scan), polling the
task list every poll_s seconds (0.5-30) for up to timeout_s (1-7200).
Reports progress to the client when supported. Returns
{done, timed_out, elapsed_s, last} where last is the final task snapshot.
Inputs: poll_s, timeout_s.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools are clearly separable, but several pairs overlap: scanner_status already returns the active error list that scanner_errors returns separately, scanner_scans records already include points and file path that scanner_scanfile_info extends, and scanner_wait_for_scan is a polling wrapper around scanner_tasks. Descriptions mitigate these overlaps, but an agent still has to choose between near-duplicates.
All tools share a uniform snake_case 'scanner_' prefix, which makes the set very readable as a family. The only minor deviation is that some tools are bare noun getters (scanner_status, scanner_projects, scanner_errors) while others use verb phrases (scanner_download_scanfile, scanner_wait_for_scan, scanner_preview_to_angles).
At 11 tools the set is well-scoped for an instrument-control server: inspection (status, projects, scans, modes, errors, tasks), acquisition helpers (wait_for_scan, file info, two downloads), and one geometry converter each earn their place. Nothing feels padded or redundant by count.
Descriptions repeatedly reference scanner_launch_scan and scanner_launch_area_scan, but neither tool is present, so scanner_preview_to_angles and scanner_wait_for_scan point at operations the agent cannot perform — a severe dead end for the core workflow of actually starting a scan. There are also no create/delete operations for projects or scans, only listings.
Maintenance
Related MCP Connectors
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
Host any HTTP API as a standard MCP server; auto-distribute to 12+ mainstream agent platforms.
Agent-readiness scanner (0-5 score), robots.txt + llms.txt generators, managed agent enablement.
Free agent-service discovery, OpenAPI document checks, and receipt verification. No API key needed.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables agents to query LAVA board farms, submit and manage test jobs, and open interactive board sessions via the LAVA REST API.2MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to query Bambuddy-managed 3D printers' status, current prints, diagnostics, camera snapshots, and archived print sources, and to safely start prints via a two-stage confirmation token while keeping sensitive credentials out of MCP output.9AGPL 3.0
- FlicenseNot gradedqualityCmaintenanceEnables local Mac agents to monitor and control Bambu Lab 3D printers via MCP tools, including status checks, camera snapshots, and print job management.-
- AlicenseNot gradedqualityBmaintenanceEnables an agent to inspect, slice, upload, start, and monitor jobs on a Moonraker/Klipper 3D printer end to end, using one JSON profile for machine-specific configuration. Built-in safety checks block unsafe starts such as incomplete G-code, nozzle mismatches, hot beds, or running jobs.MIT