spooly.eu/docs/ai/tools

Tool reference

All 23 tools of the MCP server, sorted by topic. They return the same data as the REST API.

Open as text

On this page

For all tools

Tools that change something need the permission to change. They also take an optional request_id: with the same ID, a retry runs only once.
Lists return total, and the AI pages through with limit and offset.
Weights are in grams, costs in the currency from get_account.
Spool names, notes and printer names are data. Spooly tells the AI not to follow instructions inside them.

Account

Tool	What it does	Parameters
`get_account`	Account type (Pro or Trial), calls today, daily limit, key name and currency	None
`get_attention`	What is due today: maintenance due, number of prints waiting for review, and low spools	None

Spools

Tool	What it does	Parameters
`list_spools`	Spools by number, with remaining weight, size and warning level	`limit` 1 to 500, default 100; `offset`; `archived` default false
`get_spool`	One spool	`spool_id`: the `id` from `list_spools`, not the spool number
`create_spool` changes	Creates a spool. Without a remaining weight it is full.	Required in `spool`: `color_hex` as #RRGGBB, `material` (with its variant, such as PLA Basic), `spool_size_grams`. Optional: `name`, `color_name`, `manufacturer`, `finish`, `remaining_grams`, `empty_spool_grams`, `price`, `notes`, `location_id` and with it `place`. The names are the same as in `list_spools`.
`update_spool` changes	Changes the fields sent for a spool. Weight goes through `set_spool_weight` and `refill_spool`.	`spool_id`, `changes`: the same fields as when creating, without remaining weight, so `color_hex`, `material`, `spool_size_grams`, `name`, `color_name`, `manufacturer`, `finish`, `empty_spool_grams`, `price`, `notes`, `location_id`, `place`
`set_spool_weight` changes	Sets the remaining weight. 0 g archives the spool, as in the app.	`spool_id` and exactly one of: `grams` 0 to 20,000 or `gross_grams` 0 to 40,000
`refill_spool` changes	Adds grams. The result must not exceed the spool size.	`spool_id`, `grams` above 0 up to 20,000
`archive_spool` changes	Archives a spool, its print history stays. Not possible during a running print.	`spool_id`
`restore_spool` changes	Brings an archived spool back.	`spool_id`
`move_spool` changes	Puts a spool into a storage location.	`spool_id`, `location_id`; null takes it out of the location; optional `place` for a place

Slots

Tool	What it does	Parameters
`get_slots`	Which spool sits in which slot, for example in the AMS or the ACE	None
`assign_slot` changes	Puts a spool into a slot. Only with the slot autopilot active. If the printer reports a different color, the call fails with `andere_farbe`.	`slot_id`, `spool_id`, `confirm_color`
`clear_slot` changes	Empties a slot. The spool stays in Spooly.	`slot_id`

Storage locations

Tool	What it does	Parameters
`list_locations`	Storage locations with ID, path and number of places, for `move_spool`	None

Prints

Tool	What it does	Parameters
`list_prints`	Prints, newest first, with duration, grams per spool and material cost	`limit` 1 to 200, default 100; `offset`

Printers

Tool	What it does	Parameters
`list_printers`	All printers. Online and offline only with a reliable signal, otherwise `unknown`. Progress and remaining time only for Bambu Lab.	None
`set_printer_hours` changes	Sets the total hours to the number on the device. Due dates do not jump. Less than the hours Spooly has recorded is not possible.	`printer_id`, `total_hours` 0 to 1,000,000

Maintenance

Tool	What it does	Parameters
`get_maintenance`	Maintenance book: printers with hours, tasks with status, remaining amount and an estimate in days. Device errors and AMS humidity only concern Bambu Lab.	None
`list_maintenance_log`	Maintenance history, newest first	`task_id`, `printer_id`, `limit` 1 to 200, default 50; `offset`
`complete_maintenance` changes	Marks a maintenance as done, only when you said so. The counter starts over and parts are deducted from stock. This does not create a new nozzle or plate.	`task_id`, `action` (`replace`, `clean`, `check`), `notes` up to 1,000 characters
`snooze_maintenance` changes	Reminds you about a maintenance later.	`task_id`, `days` 7, 14 or 30, `reason` up to 200 characters

Statistics

Tool	What it does	Parameters
`get_statistics`	Prints, failed prints, grams, hours, filament cost, the equally long period before, materials, printers, most used spools and stock value. Months follow the time zone of the account.	`year` 2000 to 2100, `month` 1 to 12. Without them, everything.