Skip to main content
Glama

norns-mcp

MCP server and CLI (nornsctl) for a monome norns on the local network. v0.1.

Status: work in progress, building in public. v0.1 works against a real norns; expect breaking changes.

Shares its device core design with m8-mcp (see docs/CORE.md).

What it does

Tools

Path

Reads (any time)

norns_status, norns_list_scripts, norns_current_script, norns_read_script, norns_params, norns_get_param, norns_logs, norns_dust_inventory

SSH (ssh norns), matron REPL ws :5555

Writes (gated)

norns_screenshot, norns_load_script, norns_start_script, norns_stop_script, norns_set_param, norns_key, norns_enc

matron REPL, OSC :10111

Deploy (gated)

norns_deploy

rsync over SSH

Related MCP server: mcp-remote-docker

Safety

  • Writes are dry runs unless the server/CLI is started with --live (the only switch; no env var), and even then each call needs confirm=true (--confirm on the CLI). A dry run returns data.would_send (the exact Lua / OSC / rsync) and sends nothing.

  • No sudo, no system or firmware commands, nothing that deletes on the norns: every remote command goes through an allowlist (safety.check_remote_argv); rsync never gets --delete or similar (safety.check_rsync_argv).

  • Deploy: rsync dry run first, always. Live: cp -a backup of the existing folder to ~/norns-mcp-backups/<name>-<UTC> on the norns, backup checked, then push, then per-file SHA-256 check against the Mac.

  • Lua goes to matron as one line with nonce markers (lessons from the iMac norns-mcp-server: multi-line sends corrupt matron's REPL buffer).

  • The only file written outside deploy is the screenshot temp file /tmp/norns-mcp-screen.png; screenshot is gated like any write.

Use

uv sync
.venv/bin/nornsctl status            # reads
.venv/bin/nornsctl scripts | current | params | get <id> | logs [unit] -n 50 | read awake
.venv/bin/nornsctl inventory --compare-backup --hashes
.venv/bin/nornsctl --live screenshot --confirm   # gated: writes one /tmp file on the norns
.venv/bin/nornsctl load awake        # DRY RUN
.venv/bin/nornsctl --live load awake --confirm    # real (check nobody else is playing first)
.venv/bin/nornsctl deploy ~/path/to/myscript      # DRY RUN plan

MCP (stdio), dry run: .venv/bin/norns-mcp. Live: .venv/bin/norns-mcp --live. Not registered in any client yet.

Tests

uv run pytest (fakes, no device). uv run pytest -m device (read-only, real norns).

Roadmap

  • Verify every live write on hardware (keys, encoders, OSC /param path)

  • Extract the shared device core into a package used by norns-mcp and m8-mcp

  • Safe recovery from the SYSTEM > RESTART / JACK hang over SSH

  • Multi-script coordination from the host (see docs/MULTI-SCRIPT.md)

  • Packaging and a one-line install for other norns owners

Licence

MIT, see LICENSE.

Available Tools

16 tools
norns_current_scriptA

The running script (name, path, engine, param count) from matron. name 'none' means nothing is loaded.

Inputs: no named parameters. Returns: object

norns_deployA

WRITE. Push a script folder from this Mac to ~/dust/code// with rsync over SSH. Always runs an rsync dry run first and returns the plan. Never deletes on the norns (no --delete). Live (needs --live and confirm=true): backs up the existing folder to ~/norns-mcp-backups/ first, then pushes, then checks sha256 per file.

Inputs: local_dir (required), name, confirm. Returns: object

norns_dust_inventoryA

Files and bytes in dust per top folder and per script. compare_backup=true checks against the Mac backup's MANIFEST.sha256 by path and size; hashes=true also compares sha256 for files present in both (slower).

Inputs: hashes, compare_backup. Returns: object

norns_encA

WRITE. Turn encoder n (1-3) by delta (-64..64, not 0) over OSC. Dry run unless --live; live needs confirm=true.

Inputs: n (required), delta (required), confirm. Returns: object

norns_get_paramC

One param's raw value and display string.

Inputs: param_id (required). Returns: object

norns_keyA

WRITE. Press key n (1-3) over OSC; z=1 down / z=0 up, omitted = press and release. Dry run unless --live; live needs confirm=true.

Inputs: n (required), z, confirm. Returns: object

norns_list_scriptsA

Every folder in ~/dust/code with its .lua files. data.scripts[].loadable lists the names norns_load_script accepts ('awake' or 'folder/file').

Inputs: no named parameters. Returns: object

norns_load_scriptA

WRITE. Load a script by name ('awake' or 'folder/file'); replaces the running one. Dry run unless --live; live needs confirm=true.

Inputs: script (required), confirm. Returns: object

norns_logsA

journalctl for norns-.service: matron (Lua, script errors), crone, sclang, maiden, jack, watcher. lines 1-2000; since like '10 min ago' or '2026-10-20 18:00'. hide_repl_echo drops this server's own REPL traffic from the matron journal.

Inputs: unit, lines, since, hide_repl_echo. Returns: object

norns_paramsB

All params of the running script plus the system params: index, id, type, name, raw value and the display string the norns shows.

Inputs: no named parameters. Returns: object

norns_read_scriptA

Source of a script: script='awake' reads awake/awake.lua; file='lib/x.lua' reads another file in that folder. Read only, max 256 KB.

Inputs: script (required), file. Returns: object

norns_screenshotA

WRITE (small). Grab the norns screen (640x384 PNG of the 128x64 display) to the Mac. It makes matron write one fixed temp file on the norns (/tmp/norns-mcp-screen.png), so it is dry run unless --live; live needs confirm=true.

Inputs: confirm. Returns: object

norns_set_paramA

WRITE. Set a param (option params take the 1-based index) and read it back. via='repl' (default, verified path) or 'osc' (/param/, unverified). Dry run unless --live; live needs confirm=true.

Inputs: value (required), param_id (required), via, confirm. Returns: object

norns_start_scriptA

WRITE. Start a script (same as load). With no name, start the last script the norns remembers. Dry run unless --live; live needs confirm=true.

Inputs: script, confirm. Returns: object

norns_statusA

SSH reachable, norns version, service states, REPL reachable, running script, and whether this server is live. Sends nothing that changes the norns.

Inputs: no named parameters. Returns: object

norns_stop_scriptA

WRITE. Stop the running script and free its engine (what K1+K3 'stop' does on the home menu). Dry run unless --live; live needs confirm=true.

Inputs: confirm. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools target a distinct resource+action pair, and read vs write surfaces are clearly separated. The main soft spot is norns_load_script vs norns_start_script, which the description itself admits are the same operation (start with no name = last script), and norns_status overlaps slightly with norns_current_script on running-script info.

    Naming Consistency5/5

    Every tool uses the same norns_<verb>_<noun> snake_case pattern (norns_list_scripts, norns_read_script, norns_set_param, norns_stop_script). Verbs are used predictably for reads vs mutations, so the convention is easy to internalize.

    Tool Count4/5

    16 tools is on the high side of the ideal band, but each maps to a real device operation (status, script lifecycle, params, logs, inventory, input injection, deploy). Nothing looks redundant enough to cut, though load/start could arguably be merged.

    Completeness4/5

    The surface covers the full lifecycle for the core domain: inspect state, list/read/load/start/stop scripts, read and set params, view logs and dust inventory, inject input, screenshot, and deploy. Gaps are minor and partly intentional (no delete/rm on the norns, no file-write or engine-specific controls beyond stop).

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers