dglab-mcp
This server lets MCP clients safely control DG-LAB Coyote V2/V3 electrostimulation hardware through natural-language tools, with pairing, telemetry, intensity management, waveforms, and safety overrides.
Pair:
dglab_connectreturns a QR code/session link for the DG-LAB 4 app;dglab_disconnectstops output and destroys the session.Monitor:
dglab_get_statusreports relay state, safety lease, paired apps, devices (battery, Bluetooth, channel intensity/condition, limits), and waveform tasks.Control intensity:
dglab_set_intensitysets an absolute A/B target (0-200, capped at 30 by default);dglab_adjust_intensityapplies a signed delta (+5 max upward).Play waveforms:
dglab_list_waveformslists built-in and hot-loaded.pulsefiles;dglab_play_waveformplays a named waveform;dglab_play_custom_waveformcompiles ramp/hold/pulse/silence segments.Stop safely:
dglab_stop_channelclears one channel;dglab_emergency_stopimmediately stops all channels and tasks.Keep alive:
dglab_heartbeatrenews the 20s safety lease to prevent watchdog shutdown.Configure/provision: optional environment caps and
--presetsources import.pulsewaveform collections.
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., "@dglab-mcp Pair my Coyote and show me the QR code"
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.
@zakotoys/dglab-mcp
Safety-first Model Context Protocol server for DG-LAB Coyote V2/V3 hardware. It connects Claude Desktop, Cursor, OpenCode, Codex, or any MCP client to the DG-LAB 4 V4 WebSocket relay through a local stdio process.
Safety first
This software controls a device that delivers real electrical stimulation to a human body. Use it only with informed consent, active human supervision, and the physical device within reach.
Default ceiling:
30/200(DGLAB_MAX_INTENSITY); higher targets are rejected.Default step limit:
5(DGLAB_MAX_STEP) for each upward command.Watchdog: output is set to zero after 20 seconds without a command or heartbeat.
Emergency stop:
dglab_emergency_stopclears every device and queued task.
Related MCP server: InstrMCP
Features
Natural-language control through standard MCP tools.
QR pairing with the DG-LAB 4 mobile app; no computer Bluetooth is required.
Live battery, connection, channel, and task telemetry.
Built-in presets, custom waveforms, and hot-loaded
.pulsefiles.Hard safety caps, step guards, telemetry gating, per-channel queues, and a global control lease.
Requirements
Node.js 22 or newer.
DG-LAB 4 on iOS or Android, with a Coyote V2 or V3 paired over Bluetooth.
Claude Desktop, Cursor, OpenCode, Codex, MCP Inspector, or another MCP client.
Quick start
Claude Desktop, Cursor, OpenCode, or Codex
Use this MCP server command in the client's configuration:
{
"command": "npx",
"args": ["-y", "@zakotoys/dglab-mcp@latest"]
}To install .pulse files from any supported source, add --preset (or -p)
and its source. For example, this imports a GitHub tree recursively:
{
"command": "npx",
"args": [
"-y",
"@zakotoys/dglab-mcp@latest",
"--preset",
"https://github.com/zakotoys/dglab-pulse-collect/tree/main/pulses/pulse-001"
]
}By default, synchronization fails when any downloaded .pulse file is invalid.
Add --skip-invalid-presets to ignore invalid waveform files and import only the
valid files from each source. Download failures, oversized responses, and other
source errors still fail the synchronization.
For Windows clients that require it, use cmd:
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@zakotoys/dglab-mcp@latest"]
}Embed the object above under the client's MCP server map. Examples:
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"dglab": {
"command": "npx",
"args": ["-y", "@zakotoys/dglab-mcp@latest"]
}
}
}Cursor (~/.cursor/mcp.json or .cursor/mcp.json):
{
"mcpServers": {
"dglab": {
"command": "npx",
"args": ["-y", "@zakotoys/dglab-mcp@latest"]
}
}
}OpenCode (opencode.json):
{
"mcp": {
"dglab": {
"type": "local",
"command": ["npx", "-y", "@zakotoys/dglab-mcp@latest"]
}
}
}Codex (~/.codex/config.toml):
[mcp_servers.dglab]
command = "npx"
args = ["-y", "@zakotoys/dglab-mcp@latest"]MCP Inspector
npx @modelcontextprotocol/inspector -y @zakotoys/dglab-mcp@latestConnect over stdio, then call dglab_connect to display the pairing QR code.
Pair a device
Call
dglab_connectfrom your MCP client.Scan the returned QR code with the DG-LAB 4 app, or open its session link.
Call
dglab_get_statusand confirm that the Coyote is paired and telemetry is current.Start low, for example
dglab_set_intensitywithtarget: 3, then play a waveform. Calldglab_disconnectwhen finished; it stops output first.
Multiple apps and devices can be connected. Pass clientId and slotId when
needed; an omitted target is accepted only when exactly one compatible Coyote is
available.
MCP tools
Tool | Purpose |
| Start or reuse a relay session and return the QR code. |
| Stop all output and destroy the session. |
| Read relay, safety, device, channel, and task state. |
| Set an A/B channel target after safety validation. |
| Apply a signed, safety-checked channel delta. |
| List built-in and external waveforms. |
| Play a named waveform for a bounded duration. |
| Compile and play ramp/hold/pulse/silence segments. |
| Stop tasks and reset one channel. |
| Immediately stop every channel and task. |
| Renew the active control lease. |
Nonzero output requires a paired, supported Coyote with known telemetry. Errors
use stable codes such as NOT_CONNECTED, AMBIGUOUS_TARGET, SAFETY_LIMIT, and
INVALID_WAVEFORM.
Configuration
All variables are optional:
Variable | Default | Description |
|
| Absolute output ceiling on the 0-200 scale. |
|
| Maximum upward change per command. |
|
| Watchdog timeout for the control lease. |
|
| Maximum waveform duration. |
|
| DG-LAB V4 relay endpoint. |
|
| Directory for external |
The effective channel ceiling is the minimum of the configured limit and every limit advertised by the app or device.
External waveforms
Put official-format .pulse files anywhere under DGLAB_PULSE_DIR:
~/.dglab-mcp/pulses/
waves.pulse
favourites/
my-favourite.pulseThe directory is rescanned recursively on every list/play call. Files are limited to 64 KiB, and the catalog accepts at most 100 files. Names match built-in ids and labels case- and separator-insensitively, but matching is exact rather than fuzzy.
At startup, --preset <source>... or -p <source>... uses the same source grammar as
npx skills: local paths, GitHub/GitLab repository or tree sources, GitHub
shorthand (owner/repo), direct .pulse downloads, and well-known HTTP(S)
directory listings. GitHub and GitLab repository trees are traversed through
their repository APIs; generic HTTP directories are crawled recursively on the
same origin. Relative subdirectories are preserved. Direct git clone sources
are supported for repositories containing .pulse files. Hosted archive URLs
are recognized as download sources but are not extracted; use a direct .pulse
URL instead. Multiple sources are synchronized sequentially in the order given;
repeat --preset/-p to append more sources. The server writes manifest.json
in DGLAB_PULSE_DIR with each source, local path, and SHA-256 hash. On later
starts, a source whose local
files still match the manifest is used without another network request; missing
or modified managed files are downloaded again. Download and cache diagnostics
go to stderr so stdout remains exclusively available to MCP JSON-RPC.
Development
npm install
npm run ci # typecheck, lint, coverage, build, and pack check
npm run build # compile dist/ and make the CLI executable
npm test
npm run lint:fixThe test suite uses a fake V4 relay and fake DG-LAB app, so it does not require hardware.
Releases
GitHub Actions publishes matching vX.Y.Z tags with npm Trusted Publishing and
provenance, then creates a GitHub Release with automatically generated changelog
notes. If the workflow is rerun, an existing Release is kept unchanged.
Configure the npm package's Trusted Publisher as:
Provider: GitHub Actions
Organization/user:
zakotoysRepository:
dglab-mcpWorkflow filename:
publish.ymlEnvironment: blank
Allowed action:
npm publish
For a new checkout, bootstrap the scoped public package once while logged in to the npm organization:
npm login
npm publish --access publicThen release future versions from a clean checkout:
npm version patch # or minor / major
git push origin main --follow-tagsThe workflow runs the full CI suite and publishes only when the tag matches the
version in package.json.
Scope
This project supports Coyote V2/V3 through the DG-LAB 4 V4 relay only. Legacy V3 relay, direct BLE, HTTP transport, GUI, raw frames, and Opossum output control are outside the current scope.
License
Available Tools
11 toolsdglab_adjust_intensityAdjust channel intensityA
Apply a signed intensity delta to one channel. Positive deltas are limited to +5 per call and to the effective ceiling; negative deltas are unrestricted.
Inputs: delta (required), channel (required), slotId, clientId.
dglab_connectConnect DG-LAB relayAIdempotent
Start (or reuse) the DG-LAB 4 V4 relay session. Returns the pairing QR code (PNG), the app socket URL, and the session link. Scan the QR code or open the link with the DG-LAB 4 mobile app to pair. Safe to call again to fetch pairing info for an existing session.
Inputs: no named parameters.
dglab_disconnectDisconnect relay sessionADestructiveIdempotent
Emergency-stop every device, then destroy the relay session and all cached pairing state.
Inputs: no named parameters.
dglab_emergency_stopEmergency stopADestructiveIdempotent
Immediately stop every channel and waveform task on every paired app and device, bypassing all queues. Cannot be undone by pending commands.
Inputs: no named parameters.
dglab_get_statusGet DG-LAB statusARead-onlyIdempotent
Read relay state, the safety lease, paired apps, devices (battery, Bluetooth state, A/B intensity, channel condition, mute, comfort limits, effective ceilings), and waveform tasks. Set refresh to re-query device lists from the apps first.
Inputs: slotId, refresh, clientId.
dglab_heartbeatRenew safety leaseARead-onlyIdempotent
Renew the control lease (timeout 20000ms) to keep output enabled while idle. When no output is active this succeeds as a no-op. If the lease ever expires, all outputs are stopped automatically.
Inputs: no named parameters.
dglab_list_waveformsList waveformsARead-onlyIdempotent
List built-in Coyote presets and external .pulse waveforms with ids, labels, source, and natural duration. The pulse directory is rescanned on every call, so newly added or changed files appear immediately.
Inputs: no named parameters.
dglab_play_custom_waveformPlay custom waveformA
Compile and play semantic waveform segments (ramp, hold, pulse, silence) on one channel. Total duration is capped at 10000ms. Requires a safe nonzero intensity on the channel; never changes intensity.
Inputs: channel (required), segments (required), slotId, clientId.
dglab_play_waveformPlay named waveformA
Play a named waveform (built-in preset or hot-loaded .pulse file; matching is case/separator-insensitive across ids and English/Chinese names) on one channel. Optionally repeat or truncate it to durationMs (max 10000ms). Requires a safe nonzero intensity on the channel; never changes intensity. Playback replaces the channel's current waveform task.
Inputs: name (required), channel (required), slotId, clientId, +1 more.
dglab_set_intensitySet channel intensityAIdempotent
Set one output channel (A or B) to an absolute target on the 0-200 scale. The target must not exceed the effective ceiling (software cap DGLAB_MAX_INTENSITY=30 tightened by device limits) and increases are limited to steps of 5. Reductions and 0 are always allowed.
Inputs: target (required), channel (required), slotId, clientId.
dglab_stop_channelStop channelADestructiveIdempotent
Clear all waveform tasks and reset the intensity of one channel to 0.
Inputs: channel (required), slotId, clientId.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct concern: session lifecycle, status, channel stopping, absolute vs. relative intensity, waveform discovery, file-based vs. custom playback, emergency stop, and lease renewal. Even similar tools like set_intensity and adjust_intensity are clearly separated by absolute vs. delta semantics.
All tools share the dglab_ prefix and mostly follow a verb_object pattern: connect, disconnect, stop_channel, set_intensity, play_waveform. The main deviation is dglab_heartbeat, which is a noun rather than a verb_object command, but it remains predictable and readable within the set.
Eleven tools is well-scoped for a device-control server. Each tool covers a meaningful part of session management, safety, intensity control, and waveform playback without excessive fragmentation.
The tool surface covers the full control lifecycle: connect, disconnect, status, intensity, waveform playback, emergency stop, and lease renewal. A minor gap is that status exposes settings like mute and comfort limits, but there are no direct tools to modify those settings.
Maintenance
Related MCP Connectors
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Chat, image, video, and audio models from many vendors behind one remote MCP server and one key.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAI-native oscilloscope control. A pure-Python MCP service that lets LLM agents control Keysight EDUX1052G oscilloscopes via a compact DSL.MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for quantum device physics laboratory instrumentation control, enabling LLMs to interact with physics instruments and measurement systems through QCodes and JupyterLab.39MIT
- AlicenseAqualityBmaintenanceMCP server that lets AI assistants control Siglent SDG waveform generators over a local network using natural language, supporting signal generation, modulation, sweep, burst, and arbitrary waveforms.20514 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables natural language control of a live GNU Radio SDR flowgraph, allowing users to tune frequencies, adjust gain, capture IQ samples, analyze spectra, and detect signals through an MCP-compatible client.2MIT