norns-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@norns-mcp what script is currently running on my norns?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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) |
| SSH ( |
Writes (gated) |
| matron REPL, OSC :10111 |
Deploy (gated) |
| 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 needsconfirm=true(--confirmon the CLI). A dry run returnsdata.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--deleteor similar (safety.check_rsync_argv).Deploy: rsync dry run first, always. Live:
cp -abackup 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 planMCP (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
/parampath)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 toolsnorns_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
Scored across 16 tools
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.
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.
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.
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
Related MCP Connectors
SSH client, server management and one remote MCP URL for your machines, with human approvals.
Manage servers through SSH.
Four public utilities plus seven OAuth-protected Remote read tools for paired Nymrel devices.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides full administrative control of OpenWRT routers via SSH, with a preview-confirm safety model for mutating operations.17 npmMIT
- AlicenseNot gradedqualityDmaintenanceManages Docker containers, images, and Compose stacks on a remote host over SSH, with file sync and deploy orchestration.MIT
- AlicenseBqualityCmaintenanceEnables control of a local Sonic Pi runtime to run code, stop jobs, read events, and search docs/samples/synthdefs via OSC messages.191MIT
- FlicenseAqualityCmaintenanceEnables managing remote hosts from ~/.ssh/config over OpenSSH, including availability checks, command execution with sudo and timeouts, background jobs, SSH config and known_hosts management, and llms.txt-based documentation retrieval.19-