This MCP server lets an AI assistant connect to, monitor, and control CNC machines via Universal GCode Sender (UGS), with built-in safety confirmation mechanisms to prevent autonomous machine movement.
Connection Management
Connect to a CNC machine via serial port (configurable firmware and baud rate), disconnect, and troubleshoot issues by listing available ports and checking pendant reachability.
Machine & Job Status
Retrieve real-time machine state (Idle/Run/Alarm), current position, feed rate, spindle speed, and monitor running job progress.
Motion Control (Token-Protected) All motion commands require a two-step token confirmation — the AI cannot self-confirm movement:
Jog a single axis (X, Y, or Z) by a specified distance and feed rate
Run the homing cycle ($H)
Rapid return to G54 work zero (X0 Y0 Z0)
Set G54 work coordinate offsets at the current position
Stream and run G-code files (with a built-in safety check and preview before execution)
Execute saved macros by name
Job Control
Pause a running job (feed hold)
Cancel a running job (uses a simple boolean confirmation instead of a token, since stopping is always safer)
G-code Analysis & Macros
Translate G-code into plain English, line by line, with machine state context
Perform safety checks (spindle off during cuts, missing unit declarations, zero feedrate on cut moves, etc.)
Estimate cycle time from feed rates and distances (returns HH:MM:SS)
List all tools referenced in a file with first-use line and usage count
Save validated G-code snippets as named, reusable macros
List all saved macros with names and descriptions
MCP server for controlling CNC machines via Universal GCode Sender.
Lets Claude (or any MCP-compatible AI assistant) connect to a CNC machine, inspect G-code, and issue motion commands — all through the UGS Pendant REST API.
This software controls machines that can damage equipment, destroy parts, and injure or kill people.
CNC machines move fast and don't know where your hands are. Before you use this:
Read SAFETY.md. All of it.
Understand the token confirmation system that prevents Claude from moving your machine autonomously.
Know where your E-stop is.
If you skim the safety docs and something goes wrong, that's on you. We warned you.
Related MCP server: CNCjs MCP Server
Connection tools — Connect/disconnect UGS to your CNC, troubleshoot serial port issues
Status tools — Read machine state, position, feed rate, spindle speed
Motion tools (token-protected) — Jog axes, home, return to work zero, run G-code files and macros
G-code inspector — Translate G-code to English, safety check, cycle time estimate, tool list
Every motion command uses a two-step token protocol: Claude generates a token, shows it to you, and the machine only moves when you read the token back. Claude cannot bypass this — tokens are generated and validated server-side.
Universal GCode Sender 2.x (winder.github.io/ugs_website)
UGS Pendant plugin installed and active (Tools → Plugins → Installed)
Pendant running at http://localhost:8080 (default)
Python 3.11+
pip install ugs-mcpgit clone https://github.com/zackpeters93/ugs-mcp.git
cd ugs-mcp
pip install -e .claude mcp add ugs-cnc ugs-mcpOr from source (without pip install):
claude mcp add ugs-cnc /path/to/ugs-mcp/ugs_mcp/run_server.shIn ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"ugs-cnc": {
"command": "ugs-mcp"
}
}
}Or from source:
{
"mcpServers": {
"ugs-cnc": {
"command": "/opt/homebrew/opt/python@3.11/libexec/bin/python3",
"args": ["-m", "ugs_mcp.server"],
"cwd": "/path/to/ugs-mcp"
}
}
}Environment variables (all optional):
Variable | Default | Description |
|
| UGS Pendant host |
|
| UGS Pendant port |
|
| Directory for saved G-code macros |
|
| Rapid speed used in return-to-zero |
Copy .env.example to .env to customize.
Every motion tool uses a mandatory two-step confirmation:
Step 1 — Call the tool without a token. Claude shows you a preview (axis, distance,
resulting position, safety warnings) and a token like [A3F8B2C1].
Step 2 — Read the preview. If you agree, tell Claude the token. Claude calls the tool
again with confirmation_token="A3F8B2C1". The machine moves.
Tokens are generated server-side via uuid4(), expire in 2 minutes, and are single-use.
Claude cannot predict, fabricate, or reuse them. The only way movement happens is if you
type the token back.
See USER_GUIDE.md for the full tool reference with parameters, examples, and typical workflows.
Category | Tools |
Connection |
|
Status |
|
Job |
|
Motion |
|
G-code |
|
SainSmart Genmitsu 3018 Pro (GRBL)
UGS 2.x with Pendant plugin
macOS / Python 3.11
Likely works with any GRBL-based machine. TinyG/FluidNC/Smoothieware untested.
MIT — see LICENSE.
No warranty. No liability. Read SAFETY.md.
Estimate machining cycle time from G-code feedrates and distances. Returns HH:MM:SS.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path_or_code | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states the mechanism (from feedrates and distances) and output format, but fails to disclose error handling, assumptions (e.g., valid G-code), or any potential limitations (e.g., complex toolpaths).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus output format note, with no redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the availability of an output schema, the description still lacks completeness: no clarification for the parameter, no error scenarios, and no mention of prerequisites. The minimal information is insufficient for a tool with one required parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'file_path_or_code' has no description in the schema (0% coverage) and the tool description does not explain it. The agent cannot infer whether it expects a file path, inline G-code, or what format is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool estimates machining cycle time from G-code feedrates and distances, and specifies the output format (HH:MM:SS). This distinctly differentiates it from sibling tools which handle listing, translating, or running G-code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., gcode_safety_check or gcode_translate). There are no exclusions or contextual hints about prerequisites or appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all saved macros with their names and descriptions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes output (list of macros) but does not explicitly state it is read-only, has no side effects, or how it handles empty results. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 9 words with no extraneous content. Information is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an output schema (presumably describes return format), the description is complete for a simple listing tool. No additional context is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100% by default. Baseline score of 4 is appropriate since description adds no extra parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all saved macros with names and descriptions, using specific verb and resource. It distinguishes from sibling tools like gcode_run_macro or gcode_save_macro.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or when not to use vs alternatives. Usage is implied (e.g., to view available macros before running one), but no exclusions or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tools referenced in a G-code file, with first use line and usage count.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path_or_code | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the core behavior (listing tools with first use line and usage count) but lacks details on what constitutes a tool reference, error conditions, or performance notes. Since no annotations are provided, the description carries the burden, and while adequate, it could be more comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded with the key action and output. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool has an output schema (reducing the need to describe return values), the parameter ambiguity makes the description incomplete. For a simple listing tool, the minimum is met but not exceeded.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'file_path_or_code' has 0% schema description coverage and the tool description does not clarify what it expects (file path vs. G-code string). This is a critical gap that prevents correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List all tools referenced in a G-code file, with first use line and usage count.' It uses a specific verb ('List') and specifies the resource ('tools in a G-code file'), distinguishing it from sibling tools like gcode_list_macros.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as gcode_list_macros. It does not mention any prerequisites, limitations, or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a saved macro by name. Call with no token first to get the G-code preview, safety check, and confirmation token. The user must provide the token back before the macro runs. Claude CANNOT self-confirm - the token enforces this at the server level.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| confirmation_token | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the two-step confirmation process, the token mechanism at server level, and the safety check. It covers what happens (preview, confirmation needed) without concealing any behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each necessary. No redundancy, front-loaded with the primary action. Efficiently communicates workflow, constraints, and rationale.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two parameters, an output schema (not shown but exists), and no annotations, the description covers the workflow and safety. Could be slightly more complete by noting output format or error cases, but the output schema likely covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning: 'name' is the macro to run, and 'confirmation_token' is explained as the token from the first call. It correctly implies the token is optional initially. However, it could be more explicit about the default value behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Run a saved macro by name' - a specific verb ('Run') and resource ('saved macro') with scope. It distinguishes from sibling tools (e.g., gcode_save_macro, gcode_list_macros) by focusing on execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit step-by-step usage: call with no token first to get preview/safety check/token, then user must provide token back. Also states 'Claude CANNOT self-confirm', which is critical guidance for proper invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check G-code for safety issues: spindle off during cuts, missing unit declaration, zero feedrate on cut moves, and other DANGER/WARNING/CAUTION issues. Run this before ugs_run_file for any G-code you did not write yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path_or_code | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It lists what it checks but does not specify return format, side effects (assumed read-only but not stated), or how results are communicated. Lacks clarity on what happens after the check.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, concise and front-loaded with the action. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (not shown), the description does not describe what the output contains (e.g., list of issues, severity). For a safety tool, this is a notable gap. It covers the basic purpose but lacks completeness on results and parameter clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'file_path_or_code' has zero schema description coverage, and the description does not clarify whether it expects a file path or inline G-code string. This ambiguity hinders correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks G-code for safety issues and lists specific examples (spindle off, missing unit declaration, zero feedrate). It distinguishes itself from sibling tools like gcode_estimate_time and ugs_run_file by focusing on safety verification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends running this tool before ugs_run_file for unfamiliar G-code. While it doesn't state when to skip, the context implies it's not needed for self-written code.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a G-code macro to the macros directory after running a safety check. Claude writes the G-code content; this tool handles validation and persistence. Use gcode_list_macros to see saved macros, gcode_run_macro to execute one.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| gcode_content | Yes | ||
| description | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Mentions safety check and validation/persistence, but fails to disclose details like overwrite behavior, naming constraints, or error handling. Significant gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no wasted words. Front-loaded with primary action, then clarifies role, then references siblings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description omits details about safety check outcomes, naming conventions, and expected output. For a tool with 3 required parameters and no annotations, this is insufficient for complete agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet description does not explain individual parameters (e.g., name, gcode_content, description). Only implies that gcode_content is written by Claude, but no added semantic meaning beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Save' and resource 'G-code macro', includes context of running a safety check, and distinguishes from sibling tools like gcode_list_macros and gcode_run_macro.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions when to use alternatives (gcode_list_macros, gcode_run_macro) and states division of labor (Claude writes content, tool handles validation/persistence), but does not provide explicit when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Translate G-code to plain English, line by line. Accepts either a file path or raw G-code string. Shows each command, its meaning, and the current machine state context.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path_or_code | Yes | ||
| max_lines | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool shows each command, its meaning, and current machine state context. This provides good insight into the output behavior, though it lacks explicit discussion of side effects or permissions (likely none needed).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding distinct value with no fluff. The primary purpose is stated first, followed by input options and output details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown), the description need not detail return values. It covers the main functionality, input methods, and output context. Could be strengthened by mentioning any limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage. The description partially explains the first parameter (file path or string) but completely ignores the second parameter 'max_lines'. This leaves significant ambiguity for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool translates G-code to plain English line by line, which is a specific verb and resource. It distinguishes from sibling tools that deal with timing, macros, or safety.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it accepts a file path or raw G-code string, providing clear input options. However, it does not explicitly guide when to use this tool versus its siblings or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel the running job. Stopping mid-cut will leave a mark on the part. Uses simple confirmed=True/False (not a token) because stopping is always safer than continuing - token friction on an emergency stop would be dangerous. Call with confirmed=False first to preview, then confirmed=True to cancel.
| Name | Required | Description | Default |
|---|---|---|---|
| confirmed | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that cancelling mid-cut leaves a mark on the part. Explains why the boolean is used instead of a token for safety. This goes beyond what annotations would require.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all essential, no wasted words. Front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a dangerous operation with one parameter. Covers behavior, safety, and usage instructions. Output schema exists but description doesn't need to detail return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema by explaining the two-step workflow (preview vs. cancel) and the safety rationale. Schema only has a boolean with default; description makes it actionable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'cancel the running job' and notes the consequence of stopping mid-cut, distinguishing it from pause or other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: use confirmed=False to preview, then confirmed=True to cancel. Explains the safety rationale for not using a token, which differentiates from cancellation in other contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect UGS to the CNC machine via serial port.
| Name | Required | Description | Default |
|---|---|---|---|
| port | Yes | ||
| baud_rate | No | ||
| firmware | No | GRBL |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but gives no insight into side effects, timeout behavior, failure modes, or whether the connection is persistent or requires reconnection after certain operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence that conveys the core function without extraneous words. However, its extreme brevity sacrifices necessary detail, which prevents a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no annotations, and an output schema (not shown), the description is incomplete. It fails to explain parameter constraints, connection behavior, or error handling. While the output schema may cover return values, the description does not address usage context or potential exceptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters with 0% coverage of descriptions. The tool description adds no information about what values are valid for 'port' (e.g., COM1, /dev/ttyUSB0), acceptable baud rates beyond the default, or possible 'firmware' options (GRBL, Marlin, etc.). This leaves agents without necessary context to set parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: connecting UGS to a CNC machine via serial port. It uses a specific verb ('Connect') and resource ('UGS to the CNC machine'), and distinguishes from siblings like 'ugs_disconnect' and 'ugs_troubleshoot_connection'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives, nor does it mention prerequisites (e.g., machine powered on, USB connected) or that this should be called before other operations like jogging or running files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Disconnect UGS from the CNC machine.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description lacks side effects, requirements, or disconnect behavior details, leaving safety implications unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, efficiently communicates the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with no parameters and an output schema; description likely sufficient when combined with schema, though return details are omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage is 100% vacuously. Description adds no extra meaning but is adequate for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Disconnect UGS from the CNC machine' clearly states the verb and resource, distinguishing it from siblings like ugs_connect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use or alternatives; implied usage only, lacking context for selection among 17 sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current job progress and machine state.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description mentions 'current job progress' but does not disclose if a connection is required, whether it is read-only, or any side effects. No annotations to supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, front-loaded with verb.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimal for a zero-parameter tool with output schema, but lacks explanation of when it is appropriate to use (e.g., idle vs. active job).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters so schema coverage is 100%. Description does not add detail about output beyond the purpose, but baseline is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it gets job progress and machine state, but does not differentiate from sibling ugs_get_status which may have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like ugs_get_status, ugs_cancel_job, etc.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current machine state: position, status (Idle/Run/Alarm), feed rate, spindle speed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It describes the return values and implies a read-only operation (get state). However, it doesn't explicitly state that it is safe and has no side effects, which is minor given the simple nature of the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 14 words with no wasted text. It efficiently conveys the tool's purpose and output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists the key return fields, and an output schema exists (though not shown). It lacks mention of prerequisites (e.g., connection needed) or error scenarios, but for a simple status tool, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so per guidelines baseline is 4. No parameter information is needed, and the schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'current machine state', and lists specific fields (position, status, feed rate, spindle speed). It distinguishes from siblings like 'ugs_get_job_status' by focusing on general machine state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking machine status but provides no explicit guidance on when to use this tool versus alternatives (e.g., ugs_get_job_status). No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the GRBL homing cycle ($H). All axes move toward limit switches at full speed. Call with no token first to get a preview and confirmation token. The user must provide the token back before homing executes. Claude CANNOT self-confirm movement - the token enforces this at the server level.
| Name | Required | Description | Default |
|---|---|---|---|
| confirmation_token | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses critical behavioral traits: axes move at full speed, requires user confirmation token, and server enforces that Claude cannot self-confirm. With no annotations, this provides necessary safety and control context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences, each delivering unique value without redundancy. Well-structured and easy to follow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the tool's purpose, usage protocol, and safety enforcement. With an output schema present (not required to document returns), description is sufficient for a simple single-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds essential meaning beyond the schema: explains the confirmation token's purpose and the two-step protocol. Schema had 0% parameter descriptions, so description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it runs the GRBL homing cycle ($H), describing the action and resource. Distinguishes from sibling tools by specifying a specific machine operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear steps: call without token to get a preview/confirmation token, then provide token. Implicitly instructs when to use (homing), but no explicit comparison to alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Jog a single axis (X, Y, or Z) by distance_mm at feedrate mm/min. Call with no token first to get a preview and confirmation token. The user must provide the token back before movement executes. Claude CANNOT self-confirm movement - the token enforces this at the server level.
| Name | Required | Description | Default |
|---|---|---|---|
| axis | Yes | ||
| distance_mm | Yes | ||
| feedrate | Yes | ||
| confirmation_token | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the two-step confirmation process and server-level token enforcement. However, it could mention safety implications of moving physical hardware, but the token flow inherently addresses risk.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: three sentences. First sentence states core action, second and third explain token process. No wasted words, front-loaded with essential info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and presence of output schema, the description covers all necessary aspects: axis selection, distance, feedrate, and the critical confirmation workflow. No obvious gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are explained in the description: axis, distance_mm, feedrate, and confirmation_token (via token flow). Schema has 0% coverage, so the description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool jogs a single axis (X, Y, or Z) by distance and feedrate, using specific verbs and resource. Among sibling tools, none duplicate this function, so it distinguishes well.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit instructions: call without token first to get a preview and confirmation token, then the user must provide the token back. Also states Claude cannot self-confirm, giving clear when-to and when-not-to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pause the currently running G-code job (sends feed hold).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It reveals the mechanism ('feed hold') but omits important behavioral traits such as whether the job can be resumed, prerequisites (job must be running), or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that efficiently conveys the tool's purpose with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema (not described), the description is minimally adequate. However, it could mention that the tool only works when a job is running and that it can be resumed later, for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters are defined, so the description does not need to add parameter details. Schema coverage is 100%, and baseline for zero parameters is 4. The description adds no parameter info, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Pause') and the resource ('currently running G-code job'), and specifies the mechanism ('sends feed hold'). It distinguishes from siblings like 'ugs_cancel_job' which cancels instead of pausing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'ugs_cancel_job'. The description implies usage for pausing a running job but does not provide when-not-to-use or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rapid (G0) to G54 work zero (X0 Y0 Z0). Call with no token first to get a preview and confirmation token. The user must provide the token back before movement executes. Claude CANNOT self-confirm movement - the token enforces this at the server level.
| Name | Required | Description | Default |
|---|---|---|---|
| confirmation_token | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the rapid movement, the target (G54 zero), and the token-based confirmation mechanism. It does not detail potential side effects on other offsets, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of three short sentences, each providing critical information: the action, the two-step process, and the constraint on Claude. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter with 0% schema coverage, the description fully explains its usage. An output schema exists (assumed adequate). The description is complete for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description explains the token parameter's purpose: call without token first, then with token. This adds essential semantic meaning beyond the schema's default and type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a rapid (G0) move to G54 work zero (X0 Y0 Z0), which is a specific verb and resource. It distinguishes itself from siblings like ugs_home and ugs_jog by targeting the G54 zero position.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly outlines a two-step process: call without token for preview/confirmation token, then provide token for execution. It also explicitly states that Claude cannot self-confirm, providing clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stream a G-code file to the machine. Runs safety check in preview mode. Call with no token first to get the safety report and confirmation token. The user must provide the token back before the job starts. Claude CANNOT self-confirm - the token enforces this at the server level.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| confirmation_token | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description fully discloses behavior: safety check in preview mode, token-based confirmation, and server-level enforcement preventing auto-start. Clearly communicates the two-step process.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Compact 4 sentences, front-loaded with primary action, logically structured from main purpose to workflow details. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers workflow and constraints adequately given output schema exists. Missing details on output format or file size limits, but these are minor given the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, description explains both parameters: file_path is the G-code file to stream, confirmation_token is obtained from first call. Adds meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool streams a G-code file to the machine, mentioning safety check and two-step process. Distinguishes from siblings like gcode_run_macro and ugs_cancel_job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs the agent to call without token first, then user provides token. States Claude cannot self-confirm, providing clear workflow guidance and constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set G54 work zero at the current machine position for the specified axes. This does NOT move the machine - only sets coordinate offsets. Call with confirmed=False first to preview, then confirmed=True to apply.
| Name | Required | Description | Default |
|---|---|---|---|
| axes | No | ||
| confirmed | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses non-movement, offset-only behavior, and preview workflow. Lacks details on reversibility or permissions, but is sufficient for safe use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, no superfluous words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two parameters, no required params, and presence of output schema, the description covers purpose, usage, and behavior adequately for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It mentions 'specified axes' and 'confirmed', but does not specify acceptable values for axes (e.g., 'X, Y, Z') or format. Provides some meaning but incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Set' and the resource 'G54 work zero at the current machine position for the specified axes'. Distinguishes itself from sibling tools (e.g., ugs_home, ugs_jog) by specifying it only sets offsets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow: 'Call with confirmed=False first to preview, then confirmed=True to apply.' Also states what it does NOT do ('This does NOT move the machine'), giving clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diagnose connection issues: lists serial ports, checks pendant reachability, suggests fixes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: it lists ports, checks reachability, suggests fixes. It is clear it is diagnostic and non-destructive, though does not explicitly state it makes no changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with purpose and includes all key actions with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple diagnostic tool with no parameters and an output schema, the description is complete enough. It could mention that it does not alter state, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the input schema is trivial. The description does not need to add parameter info, and baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool diagnoses connection issues by listing serial ports, checking pendant reachability, and suggesting fixes, which is a specific verb+resource and distinguishes it from connection management siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for connection issues but does not explicitly state when to use vs alternatives like ugs_connect, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every tool targets a distinct operation within two clear groups (gcode_ and ugs_). No two tools have overlapping purposes; even similar-sounding tools like ugs_get_job_status and ugs_get_status are clearly differentiated by scope.
All tools follow a consistent prefix (gcode_ or ugs_) combined with a verb or verb_noun pattern (e.g., gcode_estimate_time, ugs_run_file). The pattern is uniform, making it easy to infer tool behavior from the name.
With 19 tools, the server is slightly above the ideal 3-15 range but still reasonable for covering both G-code analysis and CNC control. Each tool serves a clear purpose, and no tools feel redundant.
The tool surface covers essential G-code operations (estimation, translation, safety, macros) and CNC control (connection, jogging, homing, job management). Minor gaps exist (e.g., no G-code editor, no spindle control), but core workflows are well-supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/zackpeters93/ugs-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
