Skip to content

MCP Tool Reference

These are the tools linkcad-mcp offers an agent. The agent reads their descriptions and argument schemas from the server, so you do not have to pass any of this on. This page is for checking what an agent can do and for reading its tool calls.

A drawing is identified by the handle that open_drawing returns, such as d1a2b3c-1. Paths must lie under the folders given with --root or --read-root (Connecting an AI Agent). Coordinates are integers in database units; summary.units_per_meter in inspect_drawing converts them.

Information

ToolArgumentsResult
get_statusNoneLinkCAD version, license state and the licenses held (Basic, Tools, Edit, View), the folders, and the open drawings.
list_formatsdirection: import or export (optional)Every installed format with its exact name, file filter and whether the license covers it. Other tools take these names.
list_optionsfilter: part of an option name, such as GdsIn or DxfOut; offset, limitConversion options with type, default and current value, and whether a tool call may set them.

Drawings

ToolArgumentsResult
open_drawingpaths (one or more files), format, export_format, options, layer_mapA drawing handle, its summary and the import log. The format is detected from the file when format is omitted.
inspect_drawingdrawing, view, cell, layer, offset, limitview is summary (units, bounds, counts), layers, cells, hierarchy (the cells one cell references), shape_counts (per cell, layer and shape type) or shapes (the shapes of one cell, paged).
close_drawingdrawingFrees the drawing. At most eight drawings are open at once.

Give export_format to open_drawing when the drawing will be exported. LinkCAD assigns export layer numbers and cell names while it reads a file, as the conversion wizard does, so the export format cannot be changed later. A drawing opened without it can be inspected, changed and previewed, but export_drawing refuses it with no_export_format.

options sets format options by name for this call only, for example {"GdsInIgnoreText": true}. layer_map applies a layer map file while reading and needs export_format.

Changing a drawing

ToolArgumentsResult
apply_toolsdrawing, commandsRuns tool commands in order and returns the new summary and the log.
set_layersdrawing, layers, deleteChanges layers. Each entry of layers names a layer and sets enabled (a disabled layer is not exported), color (#RRGGBB, the preview color) or rename_to. delete lists layers to delete together with their shapes.
list_plugin_toolsNoneThe installed Python tool plugins, each with its options.
run_plugin_tooltool (as module:Class), drawing, optionsRuns a plugin tool and returns its result text. Options take their short names, such as calculate_area.

commands are the commands of --apply-tool, one per array element, for example ["SetUnits(um)", "MergeOverlappingPolygons()", "Offset(0.5)"]. Lengths without a unit are micrometers. Mode commands such as SetUnits, SetFillRule and SetLayerFilter apply to the commands after them. All commands are checked against the license before the first one runs. If a command fails, the ones before it stay applied and the error names the command that failed.

set_layers checks every layer name before it changes anything. A misspelled name changes nothing and never creates a layer.

Preview

ToolArgumentsResult
render_previewdrawing, width (64 to 2048, default 1024), height (64 to 2048, default 768), window, layers, fill (default true), background (black or white)A PNG of the main cell, drawn as the LinkCAD viewer draws it, and the scale in database units per pixel. window is [xmin, ymin, xmax, ymax] in database units; layers limits the picture to those layers.

Writing files

ToolArgumentsResult
export_drawingdrawing, path, overwriteWrites the drawing in the export format chosen when it was opened and returns the files written and the export log.
convert_fileinput (one or more files), output, output_format, input_format, options, layer_map, commands, overwriteReads, runs tool commands and writes in one call, without leaving a drawing open.
get_logdrawing, which (import or export), offset, limitThe full import or export log, paged. Tool results carry the first entries of the log.

An export never replaces the file the drawing was read from. It replaces another existing file only with overwrite: true. The writer writes into a hidden folder beside the destination first, and only a successful export is moved into place, all its files together. A writer that produces several files, such as one file per layer, can be given a folder as path.

Python

ToolArgumentsResult
execute_pythoncode, drawingRuns Python code in LinkCAD’s embedded interpreter with the linkcad package. With drawing, that drawing is the global drawing. Returns standard output, standard error and the error, if any.

execute_python exists only when the server was started with --allow-python. The code runs with your user’s privileges and is not limited to the folders.

Resources and prompts

The server also offers documents and prompt templates. Clients show resources as attachable context and prompts as commands, for example /mcp__linkcad__inspect_layout in Claude Code.

NameKindContent
linkcad://guide/agentResourceHow to use the tools: the workflow, units, option names, how to verify a conversion and what each error means.
linkcad://reference/tool-applyResourceThe grammar of the tool commands.
linkcad://reference/python-apiResourceThe linkcad Python package. Only with --allow-python.
inspect_layoutPromptOpen a file and report its units, bounds, top cells, layers and log, with a preview.
convert_and_verifyPromptConvert a file, reopen the output and compare it with the source.

Errors

A failed call returns an error with a stable code, a message and, for reads and writes, the conversion log. The agent receives the same table in its guide.

CodeMeaning
invalid_argumentsThe arguments do not match the tool’s schema.
path_outside_roots, no_roots_configuredThe path is not under a folder the server was given.
path_not_writableThe folder is read-only (--read-root).
path_not_foundThe file does not exist.
file_existsThe output exists and overwrite was not given.
would_overwrite_inputThe output is the drawing’s own source file.
unknown_format, format_unavailableNo installed reader or writer has that name.
format_not_licensedThe license does not cover the format.
license_blocked, license_read_only, license_unavailableThe license does not allow this. get_status shows the state and the reason.
basic_license_required, tools_license_required, edit_license_required, view_license_requiredThe named license is missing. Nothing was changed.
no_export_formatThe drawing was opened without export_format.
read_failed, write_failedThe reader or writer failed; the log says why.
tool_failedA tool command failed. The commands before it were applied.
option_rejectedThe option does not exist or may not be set through the server, for example because it is an application setting or writes files of its own.
unknown_drawing, unknown_layer, unknown_cellNo drawing, layer or cell of that name. Names are case-sensitive.
too_many_drawingsEight drawings are open. Close one first.
python_unavailable, unknown_plugin_tool, plugin_tool_failedPython could not start, the plugin tool does not exist, or it failed.
python_errorThe Python code passed to execute_python could not run.
render_failedThe preview could not be drawn.
timeout, worker_crashedLinkCAD was restarted and every open drawing was closed.
worker_start_failed, worker_protocol_error, internal_errorLinkCAD could not be started or answered incorrectly. The server’s log, shown by the client, says why.
busyToo many calls are waiting.