RemoteMCP

An MCP server for driving Lovense toys over the Game Mode local API, with multi-channel scripting, research-grounded presets, and strict input validation.

Provenance

All code here is original. The project began as an extension of Lovense's official RemoteMCP sample, but that sample carried no license — no LICENSE file, copyright header, or terms of use appear in the zip, on the docs page, or on Lovense's GitHub org. Absence of a license is not permission: under default copyright all rights are reserved and no redistribution right is granted, so vendoring it would have kept this repository permanently private.

Transport.py is therefore an independent implementation written against the publicly documented Game Mode protocol. Wire formats and API behaviour are facts about a published interface, not copyrightable expression, and the implementation shares no code with the vendor sample. Rewriting also fixed two defects the sample had:

• It called print() on every request. This server speaks MCP over stdio, where stdout is the protocol channel, so writing diagnostics there risks corrupting the stream. Transport.py logs instead.
• Its requests had no timeout, so a stalled connection blocked the caller indefinitely — for a scheduled script, a hung thread.

Not legal advice. If it matters to you, check the terms you accepted on the Lovense developer portal, which govern regardless of what the public pages say.

Setup

cp .mcp.json.example .mcp.json    # then fill in your own path and LAN IP
uv sync

Development

uv run ruff check .          # lint
uv run ruff format .         # format
uv run mypy                  # type check (strict)
uv run pytest                # tests

Tests never touch the network: an autouse fixture in tests/conftest.py blocks socket creation outright, so no test can actuate a real device even if a transport is left unmocked.

Two naming rules are waived in pyproject.toml, both because the names are load-bearing interfaces rather than style choices: the MCP tool function names are the tool names exposed to clients, and RemoteMCP.py is named in every deployed .mcp.json. Renaming either would be a breaking change. Everything else is PEP 8 clean under ruff and mypy --strict.

Releases

Merging to main cuts a release only when version in pyproject.toml has no matching tag, so routine merges don't produce releases. The workflow builds a wheel and sdist, creates a draft release, attaches the assets, and publishes last — immutable releases lock assets at publish time and none can be added afterwards.

Release immutability is a repository setting, not a workflow option: enable it under Settings → Releases → Enable release immutability. Prove the pipeline before enabling it — once on, a tag can never be moved, deleted, or reused, so a botched test release burns that version number permanently.

Get the IP and port from Lovense Remote → Game Mode. The app's local API server only runs while the app is foregrounded — it stops on background or screen lock, and requests then fail with connection refused.

Tools

Tool	Purpose
GetToys	List connected toys with IDs, battery, and supported functions
SendFunctions	Direct control, e.g. Vibrate:10,Pump:2
SendPattern	Custom pattern from a strength sequence
SendPreset	Built-in presets, or a named preset from Patterns.py
PlayScript	Multi-channel script with independent per-channel curves
SendStopFunction	Stop everything, including a running script

Strength ranges

Vibrate and Rotate accept 0–20, but Pump only accepts 0–3. Nothing enforced this originally, so out-of-range pump values were silently clamped to maximum by the toy — a pattern sweeping 0–20 across v,p held suction at full for most of its run rather than following the intended arc. Both entry points now validate per-feature ceilings.

One subtlety: when a pattern lists v,p together, the strength list is the vibration curve and pump is derived from it, so 0–20 remains legal there. Only a pump-only pattern caps at 3.

Patterns vs scripts

The Pattern command derives pump and rotation strength from the vibration values, so it cannot give them an independent curve. The trade-off:

• SendPattern / SendPreset — uploaded once and executed on the phone, so playback survives a dropped connection. Single curve only.
• PlayScript — issues timed commands so vibration and suction can counterpoint each other, but needs the connection alive for the whole run.

Patterns.py carries an edgeplay single-curve fallback mirroring the edgeplay script, for when the connection is unreliable.

Presets

Name	Type	Length	Notes
slowburn	pattern	50s loop	Tease → build → burst arc
edgeplay	pattern	300s	Single-curve fallback for the script below
edgeplay_motif	pattern	20s	Shareable distillation, fits the in-app editor
edgeplay	script	300s	Dual-channel, vibration and suction alternating

Design basis

edgeplay is built on measured physiology rather than intuition:

• Sustained amplitude is the lever that crosses threshold. At a fixed 100 Hz, 1mm peak-to-peak amplitude produced ejaculation in 32% of men versus 96% at 2.5mm — amplitude mattered, frequency did not (Sønksen et al. 1994, 10.1038/sc.1994.105). Hence three 75-second plateaus rather than spikes.
• Vibrotactile adaptation is central, not peripheral. Cuneate-neuron responsiveness stays depressed with recovery measured in minutes, and it generalizes to skin sites that were never stimulated (O'Mara, Rowe & Tarvin 1988, 10.1152/jn.1988.59.2.607). Sub-second dips restore nothing — a correction to slowburn, whose original comment claimed otherwise.
• Adaptation is channel-specific, with a 1.5–2 minute time constant; a 10 Hz adapter barely raises a 50 Hz threshold (Hollins et al. 1990, 10.3109/08990229009144707). Vibration (rapidly-adapting receptors) and suction (slowly-adapting) are therefore alternated so each channel rests while the other leads.
• Arousal lowers detection thresholds at 30/60/100 Hz (Jiao et al. 2007, 10.1007/s10508-007-9232-x), so perceived intensity rises on its own and absolute output need not climb linearly.

Literature retrieved via PubMed.

Sharing

The in-app pattern editor works on a 10–30 second timeline, so a 5-minute arc cannot be represented there. edgeplay_motif is the 20-second signature shape to redraw in the editor and share via long-press. There is no documented text-import path into the app.