Skip to main content
Glama
dglab-mcp

dglab-mcp

by zakotoys

@zakotoys/dglab-mcp

npm CI codecov License: GPL-3.0

English | 简体中文 | 日本語

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_stop clears 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 .pulse files.

  • 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@latest

Connect over stdio, then call dglab_connect to display the pairing QR code.

Pair a device

  1. Call dglab_connect from your MCP client.

  2. Scan the returned QR code with the DG-LAB 4 app, or open its session link.

  3. Call dglab_get_status and confirm that the Coyote is paired and telemetry is current.

  4. Start low, for example dglab_set_intensity with target: 3, then play a waveform. Call dglab_disconnect when 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

dglab_connect

Start or reuse a relay session and return the QR code.

dglab_disconnect

Stop all output and destroy the session.

dglab_get_status

Read relay, safety, device, channel, and task state.

dglab_set_intensity

Set an A/B channel target after safety validation.

dglab_adjust_intensity

Apply a signed, safety-checked channel delta.

dglab_list_waveforms

List built-in and external waveforms.

dglab_play_waveform

Play a named waveform for a bounded duration.

dglab_play_custom_waveform

Compile and play ramp/hold/pulse/silence segments.

dglab_stop_channel

Stop tasks and reset one channel.

dglab_emergency_stop

Immediately stop every channel and task.

dglab_heartbeat

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

DGLAB_MAX_INTENSITY

30

Absolute output ceiling on the 0-200 scale.

DGLAB_MAX_STEP

5

Maximum upward change per command.

DGLAB_HEARTBEAT_TIMEOUT_MS

20000

Watchdog timeout for the control lease.

DGLAB_MAX_WAVEFORM_DURATION_MS

10000

Maximum waveform duration.

DGLAB_RELAY_URL

wss://trex.dungeon-lab.cn/v4

DG-LAB V4 relay endpoint.

DGLAB_PULSE_DIR

~/.dglab-mcp/pulses

Directory for external .pulse files.

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.pulse

The 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:fix

The 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: zakotoys

  • Repository: dglab-mcp

  • Workflow filename: publish.yml

  • Environment: 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 public

Then release future versions from a clean checkout:

npm version patch   # or minor / major
git push origin main --follow-tags

The 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

GPL-3.0

Available Tools

11 tools
dglab_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 relayA
Idempotent

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 sessionA
DestructiveIdempotent

Emergency-stop every device, then destroy the relay session and all cached pairing state.

Inputs: no named parameters.

dglab_emergency_stopEmergency stopA
DestructiveIdempotent

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 statusA
Read-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 leaseA
Read-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 waveformsA
Read-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 intensityA
Idempotent

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 channelA
DestructiveIdempotent

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

    A4.1/5.0

    Scored across 11 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      AI-native oscilloscope control. A pure-Python MCP service that lets LLM agents control Keysight EDUX1052G oscilloscopes via a compact DSL.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for quantum device physics laboratory instrumentation control, enabling LLMs to interact with physics instruments and measurement systems through QCodes and JupyterLab.
      39
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP 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.
      20
      514 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      2
      MIT