Connect an MCP-compatible assistant or an automation tool to Ooznest Control. The MCP server runs on your computer, connects to the Ooznest Control backend and exposes machine status, G-code and control commands.
C:\examples\ooznest-control.mcp-server.js, mcp-config.json and package.json.npm install
Open the Ooznest Control desktop app and connect it to your controller through USB, Wi-Fi or Ethernet. Keep the app running: MCP connects to its backend at ws://localhost:8081, not directly to the controller's IP address or serial port. The hosted browser app alone does not provide this local backend. For a source installation, npm start launches the Electron app; node main.js does not launch it with ordinary Node.js.
These tools can move the machine, start the spindle and change settings. Begin with status queries, review movement commands before allowing them and keep a hardware stop available. Do not let a second sender control the machine at the same time.
Open mcp-config.json in a text editor. For a local assistant, start with:
{
"backendUrl": "ws://localhost:8081",
"transports": ["stdio"],
"httpPort": 3001,
"mqttBroker": null,
"mqttTopicPrefix": "ooznest/",
"apiKey": null,
"actuatorMap": {}
}
| Setting | Purpose |
|---|---|
backendUrl |
Ooznest Control backend address. Keep the default when both programs run on the same computer. |
transports |
Enable stdio, http, mqtt, or a combination. |
httpPort |
HTTP/SSE port; default 3001. |
mqttBroker |
MQTT broker address, or null to disable. A broker address also starts MQTT even if it is absent from transports. |
mqttTopicPrefix |
MQTT topic prefix; default ooznest/. |
apiKey |
Optional bearer token for the HTTP tool and SSE endpoints. MQTT uses it as its broker password. |
actuatorMap |
Map named actuators to axes and feed rates; see below. |
If you edit
mcp-config.json, restart the MCP server for your changes to take effect.
Use mcp-config.json to change the settings listed above. The command-line options --transports and --http-port, and the environment variable MCP_TRANSPORTS, are not supported and have no effect. Some other settings can be supplied through environment variables, but values in mcp-config.json take priority when the same setting is present in both places. For consistency, keep your settings in this file.
Use one controlling assistant at a time. Do not connect both VS Code's built-in MCP client and the Codex extension to control the machine simultaneously.
Run your assistant, the MCP server and Ooznest Control on the same computer for these local stdio setups. A cloud session cannot use this local connection.
Use a local stdio connection for the assistant setups below. Set "transports": ["stdio"] and "mqttBroker": null in mcp-config.json first, as shown in Step 2. Your assistant starts the MCP server automatically. Keep Ooznest Control open and connected. You do not need to start the MCP server manually.
Replace example paths with your own. JSON and TOML examples use forward slashes to avoid escaping backslashes. If the assistant cannot find node, use its full executable path. Do not put the script path in the command field: the command is node, and the script is an argument.
claude_desktop_config.json. If mcpServers already exists, add ooznest-control inside it; keep your other servers.{
"mcpServers": {
"ooznest-control": {
"command": "node",
"args": ["C:/examples/ooznest-control/mcp-server.js"]
}
}
}
Configuration file locations:
| Operating system | File |
|---|---|
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
If the server does not appear, check JSON syntax, the script path and Node.js. On Windows, inspect %APPDATA%\Claude\logs\mcp*.log; on macOS, ~/Library/Logs/Claude/.
For more help connecting Claude Desktop to a local MCP server, see the official local MCP setup guide.
mcp-server.js file./mcp to check that the server is connected.codex mcp add ooznest-control -- node "C:/examples/ooznest-control/mcp-server.js"
codex mcp list
~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows) in a text editor.mcp-server.js file. Keep any existing configuration./mcp to check that the server is connected.[mcp_servers.ooznest-control]
command = "node"
args = ["C:/examples/ooznest-control/mcp-server.js"]
For an initial read-only trial, add this inside the server's [mcp_servers.ooznest-control] block in config.toml, whichever setup method you used:
enabled_tools = ["machine_status"]
Save the file and restart Codex. When you are ready to use movement tools, remove the enabled_tools line and restart Codex again.
For more help adding and configuring MCP servers in Codex, see the official Codex MCP configuration guide.
These steps use VS Code's built-in MCP client. If you use the Codex extension instead, follow the Codex instructions above.
.vscode/mcp.json in that folder.servers already exists, add ooznest-control inside it; keep your other servers.mcp-server.js file.{
"servers": {
"ooznest-control": {
"type": "stdio",
"command": "node",
"args": ["C:/examples/ooznest-control/mcp-server.js"]
}
}
}
In your assistant, ask:
Use the ooznest-control MCP server's
machine_statustool. Report whether the controller is connected, its state and its position. Do not move it or change any settings.
Compare the reply with the Ooznest Control screen. The assistant may be connected to the MCP server while the controller is offline. If the reported state is Offline or out of date, resolve the connection before trying movement.
| Goal | Ask your assistant |
|---|---|
| Check status | “Use machine_status and summarize the connection, XYZ position, feed and spindle state. Do not move anything.” |
| Investigate an alarm | “Use troubleshoot_alarm for alarm 1. Explain the likely causes and checks. Do not unlock, reset or home the machine.” |
| Check a job | “Use job_status and report whether the job is running, paused, completed, failed or stopped. Include any error text.” |
| Prepare a program | “Draft a millimetre/G54 positioning program for the fixture coordinates I provide. Show the full G-code for review; do not load or run it.” |
| Load a reviewed program | “Load this reviewed G-code with gcode_load, filename fixture.nc. Do not start it. Confirm that Control accepted the load.” |
| Run a prepared job | “The loaded program and fixture are checked. Start it with job_run, then use job_status to report its result. Do not retry, unlock or restart after an error.” |
| Pause | “Pause the current job with job_pause and report its status. Do not resume it.” |
| Resume | “The paused job is ready to continue. Use job_resume for job ID 3, then monitor it. Do not start a new job.” |
| Stop | “Stop the current job with job_stop. This cancels the stream and resets the controller. Report its resulting state.” |
Replace job ID 3 in the resume example with the actual job ID. The assistant should pass this as the tool argument jobId.
The job API examples are pending release and require the updated Ooznest Control app/backend and MCP server described in Using Python.
completed, then reads a separate instrument and records results. See Using Python below.An assistant's answer is not a physical check of the machine or fixture. Review the tool name and arguments when the client asks for permission. Start with read-only requests; grant movement only after checking the program, work origin and clearances. A stop prompt relies on the computer connection and is not a substitute for the hardware stop.
Use HTTP to call tools from n8n or another application.
The HTTP server accepts connections on all network interfaces, and this cannot currently be changed in the configuration. An API key protects tool calls and SSE connections, but
/statusand/healthcan be read without a key. Restrict access to trusted computers and do not expose the server to the internet.
mcp-config.json in the extracted Ooznest Control folder.http and set an API key, as shown below. Replace the example key with a long, random secret.node mcp-server.js. Keep the terminal open while using HTTP.Example configuration:
{
"backendUrl": "ws://localhost:8081",
"transports": ["http"],
"httpPort": 3001,
"mqttBroker": null,
"mqttTopicPrefix": "ooznest/",
"apiKey": "replace-with-a-long-random-secret",
"actuatorMap": {}
}
Start the server:
node mcp-server.js
| Request | Purpose |
|---|---|
GET http://localhost:3001/health |
Process health, controller connection and state. |
GET http://localhost:3001/status |
Current machine and job objects. |
GET http://localhost:3001/mcp/tools |
List available tools; bearer token required when configured. |
POST http://localhost:3001/mcp/call |
Call a tool; bearer token required when configured. |
GET http://localhost:3001/sse |
SSE transport for compatible clients. The advertised message endpoint is /message. |
http://localhost:3001/mcp/call.Content-Type: application/json.Authorization: Bearer YOUR_API_KEY, replacing YOUR_API_KEY with the key in mcp-config.json.This request checks status without moving the machine:
{
"name": "machine_status",
"arguments": {}
}
The /status response contains fields such as machine.status and job.pct. A completion-notification workflow can poll status, remember that a job was running and notify only after the observed transition to idle. Idle on its own does not prove a job completed successfully.
localhostmeans the computer or container running the HTTP client. If n8n or another client runs elsewhere, replacelocalhostin the request URL with the Ooznest Control computer's reachable address, for examplehttp://192.168.0.20:3001.
The /sse endpoint works only with clients that support this server's SSE transport. The server does not provide a Streamable HTTP /mcp endpoint.
The Python job API additions in this section are pending release. Update the Control app/backend and
mcp-server.jstogether before using them. Check that/mcp/toolslistsjob_status. Older releases use a different job-start path.
Python can load, start, pause, resume, stop and monitor a job through the HTTP API. You can start a job from Python without clicking Run in Ooznest Control.
Keep one Ooznest Control desktop window open and connected. The app manages the G-code queue, controller acknowledgements, errors and alarms. You can also inspect and control the job in that window.
| Approach | Python handles | Ooznest Control handles |
|---|---|---|
| Python through this API | Preparing G-code, submitting the job, checking the result, sensor readings and application logic. | The controller connection, G-code queue, acknowledgements, job pause/resume/stop, and aborting the stream on errors, alarms or connection loss. |
| Python directly through USB/TCP | The connection, queue, acknowledgement matching, errors, alarms, disconnects, completion checks and application logic. | The app is not involved. The separate Python examples supply a basic sender, which you must maintain or extend for your project. |
C:\examples\ooznest_api.py, or in a folder of your choice.OOZNEST_API_KEY to the same key used in mcp-config.json, using the command for your operating system below.The example uses Python's standard library; no additional Python packages are required.
Windows PowerShell:
$env:OOZNEST_API_KEY = "your-api-key"
macOS/Linux:
export OOZNEST_API_KEY="your-api-key"
Replace your-api-key with your configured key. If your server has no API key configured, skip this step.
"""Load and run a G-code file through Ooznest Control; no serial library required."""
import argparse
import json
import os
import time
from pathlib import Path
from urllib.error import HTTPError
from urllib.request import Request, urlopen
class ControlAPI:
def __init__(self, url="http://localhost:3001", key=None):
self.url = url.rstrip("/")
self.key = key
def call(self, name, **arguments):
headers = {"Content-Type": "application/json"}
if self.key:
headers["Authorization"] = "Bearer " + self.key
request = Request(self.url + "/mcp/call", headers=headers,
data=json.dumps({"name": name, "arguments": arguments}).encode())
try:
with urlopen(request, timeout=20) as response:
result = json.load(response)
except HTTPError as error:
raise RuntimeError(error.read().decode("utf-8", errors="replace")) from error
if result.get("isError"):
raise RuntimeError(result)
text = result["content"][0]["text"]
return json.loads(text)
def wait_for_job(api, job_id, timeout=600):
deadline = time.monotonic() + timeout
try:
while time.monotonic() < deadline:
status = api.call("job_status")
if status["id"] != job_id:
raise RuntimeError("Job changed; check Control before continuing")
print(status, flush=True)
if status["state"] == "completed":
return status
if status["state"] in ("failed", "stopped"):
raise RuntimeError(status.get("error") or status["state"])
time.sleep(0.5)
raise TimeoutError("Job wait timed out")
except (KeyboardInterrupt, TimeoutError):
# Pause only this job. Never automatically retry a start or resume.
try:
api.call("job_pause", jobId=job_id)
except Exception as error:
print("Pause could not be confirmed:", error, flush=True)
raise
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("file", nargs="?", help="G-code file to load")
parser.add_argument("--url", default="http://localhost:3001")
parser.add_argument("--run", action="store_true", help="Start the loaded file and wait")
parser.add_argument("--action", choices=["job_status", "job_pause", "job_resume", "job_stop"])
parser.add_argument("--timeout", type=float, default=600, help="Maximum wait in seconds")
args = parser.parse_args()
if args.run and not args.file:
parser.error("--run requires a file")
if args.action and (args.file or args.run):
parser.error("Use --action separately from loading or running a file")
if not 0 < args.timeout < float("inf"):
parser.error("timeout must be a positive finite number")
api = ControlAPI(args.url, os.environ.get("OOZNEST_API_KEY"))
if args.file:
path = Path(args.file)
content = path.read_text(encoding="utf-8")
if not content.strip():
parser.error("G-code file is empty")
print(api.call("gcode_load", content=content, filename=path.name))
if args.run:
started = api.call("job_run")
wait_for_job(api, started["id"], args.timeout)
else:
print("Loaded only. Use --run after reviewing the file and setup.")
else:
print(api.call(args.action or "job_status"))
if __name__ == "__main__":
main()
The
--runoption starts machine movement without a confirmation popup in Ooznest Control. Check the program, work origin, fixture and clearances before running it.
python ooznest_api.py.python ooznest_api.py demo.nc.python ooznest_api.py demo.nc --run.Replace demo.nc with your G-code file.
Open a second terminal in the Python example's folder. If you use an API key, set OOZNEST_API_KEY in this terminal too. Run the command for the action you need:
python ooznest_api.py --action job_status
python ooznest_api.py --action job_pause
python ooznest_api.py --action job_resume
python ooznest_api.py --action job_stop
If the server runs on another computer, add
--urlwith its address, for examplepython ooznest_api.py --url http://192.168.0.20:3001. Usepython3orpyin place ofpythonif required by your Python installation.
job_status returns the job id, state, error, active, paused, connected and machineStatus. States are idle, loaded, running, completed, failed and stopped. A paused job remains running with paused: true.
The start request returns the new job ID. The Python example polls that ID so it cannot silently report a later job as the one it started. It reports success only after the streamer has received all acknowledgements and a subsequent controller report says Idle. Queue progress reaching 100% is not proof that physical movement has finished.
Errors include the failing G-code source line when available. Errors, alarms, controller resets and disconnects mark the job failed. API jobs are not automatically unlocked after an alarm. Inspect and resolve the cause before deliberately loading and starting again. Tool changes that need operator input still require the normal tool-change workflow.
Pressing Ctrl+C, or reaching the example's wait timeout, requests a pause for that same job. A pause is not cancellation; job_stop resets the controller and cancels the stream. If HTTP or the app disconnects, the outcome may be unknown: check Control and the machine before retrying. The example never automatically retries a start or resume.
While any job is active, the API rejects replacement programs, a second start and individual G-code commands. When idle, gcode_send uses Control's acknowledged command path. Its reply confirms controller acceptance, not completed movement; submit a G-code program through gcode_load / job_run when you need queued execution and a completion result.
Use MQTT to exchange machine status and commands through an existing MQTT broker.
The broker must already be running. The MCP server connects to it; it does not install a broker, install ESPHome firmware or automatically create Home Assistant entities.
MQTT uses
apiKeyfrommcp-config.jsonas the broker password. There is currently no username setting, so check that this matches your broker's authentication requirements before starting.
npm install mqtt.mcp-config.json and set mqttBroker to your broker address, for example mqtt://192.168.0.10:1883.mqtt in the transports list, for example "transports": ["mqtt"].node mcp-server.js. If it is already running, stop and restart it to load the changes.| Topic | Direction | Payload |
|---|---|---|
ooznest/status |
Published | Machine state JSON, including status and spindle. |
ooznest/job/progress |
Published | Job progress JSON, including pct. |
ooznest/ina219 |
Published | Power monitor JSON, including voltage and current, when available. |
ooznest/cmd/gcode |
Command | { "line": "..." } |
ooznest/cmd/jog |
Command | { "x": 10, "feed": 500 } |
ooznest/cmd/actuator |
Command | { "id": 1, "distance": 50, "feed": 300 } |
ooznest/cmd/job |
Command | { "action": "pause" }, resume or stop. |
The server does not publish an
ooznest/job/completetopic. If you build a completion detector, use the progress and status topics together. An idle machine or 100% progress alone does not confirm successful completion.
configuration.yaml.mqtt: section, merge the sensors into it rather than adding a second section.mqttTopicPrefix in mcp-config.json, update the topic names to match.mqtt:
sensor:
- name: "Machine Status"
state_topic: "ooznest/status"
value_template: "{{ value_json.status }}"
- name: "Spindle Speed"
state_topic: "ooznest/status"
value_template: "{{ value_json.spindle }}"
unit_of_measurement: "RPM"
- name: "Job Progress"
state_topic: "ooznest/job/progress"
value_template: "{{ value_json.pct }}"
unit_of_measurement: "%"
- name: "Power Voltage"
state_topic: "ooznest/ina219"
value_template: "{{ value_json.voltage }}"
unit_of_measurement: "V"
- name: "Power Current"
state_topic: "ooznest/ina219"
value_template: "{{ value_json.current }}"
unit_of_measurement: "A"
This is an optional feature for projects that use a controller axis to operate a mechanism, such as a TV lift. For normal CNC use, leave actuatorMap as {} and use the standard axis and job tools.
An actuator map tells the MCP server which controller axis to move when you call actuator_move with a particular actuator ID. It does not add a physical actuator or configure its wiring; the mechanism must already be connected to and configured on that axis.
Define the map in mcp-config.json. In the example below, actuator 1 is named TV Lift and uses the Z axis, with a default feed rate of 500 mm/min. Calling actuator_move with { "id": 1, "distance": 50 } requests a relative move of 50 on that axis, using the controller's current units. The name is a label for your reference; tool calls identify the actuator by its ID.
The server does not enforce the
limitsfield. Configure the controller's limits correctly; this map does not prevent travel beyond the listed range.
Example entry inside actuatorMap:
{
"1": {
"axis": "z",
"feed": 500,
"limits": [0, 200],
"name": "TV Lift"
}
}
actuator_move uses the mapped axis and feed rate to send a relative move. Restart the MCP server after changing the map.
| Tool | Description | Example |
|---|---|---|
gcode_send |
Send any G-code command | { "line": "G91 G0 Z10" } |
gcode_load |
Load G-code into buffer | { "content": "G21\\nG0 X0 Y0\\n..." } |
job_run |
Start the loaded program through Control’s job runner | {} |
job_status |
Job state, result and error from Control | {} |
job_pause |
Pause running job | {} |
job_resume |
Resume paused job | {} |
job_stop |
Stop and reset | {} |
axis_home |
Home an axis | { "axis": "z" } |
axis_jog |
Relative jog | { "x": 10, "y": 5, "feed": 500 } |
axis_move |
Move using the current distance mode | { "x": 50, "y": 30 } |
spindle_set |
Set spindle speed | { "speed": 5000, "direction": "cw" } |
spindle_stop |
Stop spindle | {} |
alarm_unlock |
Clear alarm | {} |
actuator_move |
Move named actuator | { "id": 1, "distance": 50 } |
actuator_stop |
Request feed hold (not an emergency stop) | { "id": 1 } |
probe_execute |
Send a probing command (see limitations below) | { "axis": "z", "direction": -1, "feed": 50 } |
wcs_set_offset |
Set WCS offset | { "axis": "z", "value": 0 } |
machine_status |
Full status report | {} |
| URI | Description |
|---|---|
machine://status |
Current state, positions, feed, spindle |
machine://limits |
Soft limits from grblHAL settings |
machine://pins |
Input pin states |
machine://ina219 |
Voltage and current |
job://progress |
Job streaming progress |
gcode://content |
Loaded G-code content |
actuator://config |
Configured actuator map |
| Prompt | Arguments | Use |
|---|---|---|
troubleshoot_alarm |
code (required) |
Diagnose alarm/error codes |
generate_gcode |
description (required) |
Generate G-code from description |
job_report |
— | Formatted job summary |
diagnose_connection |
— | Connection troubleshooting |
This server is experimental. Review these limitations before using movement tools:
axis_jog sends G91 G1 and leaves relative mode active. It does not use grblHAL's $J= jogging command.axis_move does not force G90, so movement depends on the controller's current distance mode.actuator_stop requests feed hold; it pauses motion rather than cancelling the program and is not a hardware emergency stop.probe_execute currently uses its feed value as the probing distance as well. Use the normal Ooznest Control probing workflow instead.job_status for an API job’s terminal result. A hardware stop remains independent of this bridge.| Problem | Check |
|---|---|
| Assistant cannot launch the server | Check node is installed, the script's absolute path is correct and npm install finished. |
| Backend will not connect | Keep the Ooznest Control desktop app running and check backendUrl. |
| Backend connects but machine is offline | Connect the controller in Ooznest Control and check its power and connection. |
| Another process is using port 3001 | Stop the duplicate process or change httpPort in mcp-config.json. |
| HTTP returns 401 | Match the Authorization: Bearer ... header to the configured apiKey. |
| An option has no effect | Change the setting in mcp-config.json and restart the MCP server. The --transports and --http-port command-line options are not supported. |
| MQTT transport is skipped | Install mqtt, configure the broker address and check broker authentication. |
| Status stops updating | Compare it with the app, check the backend connection and reconnect before relying on the values. |