vnyan-mcp

An MCP server for full-coverage control of VNyan (VTuber avatar software) from Claude or any other MCP client — parameters, triggers, blendshapes, bones, pendulums, props, colliders, node graphs, and more.

VNyan's own automation ports (REST/WebSocket/OSC) are fire-and-forget only — they can trigger things but never read state back. This project ships a small VNyan plugin that opens a real two-way bridge, plus an MCP server that talks to it, so an LLM can both drive your avatar and observe it.

What it covers

• Parameters, dictionaries, triggers — get/set VNyan's runtime variables, call named triggers, watch recent trigger activity

• Avatar — live blendshape values and overrides, humanoid bone read/write

• Pendulum chains, stretch bones, colliders, props, Spout2 cameras — read the persisted config and drive them live

• Node graphs — read, author, and export/import VNyan's visual node graphs; a generated "bridge graph" makes post-processing effects and lights controllable

• Settings — read the full settings.json config (tracking, output, graphics, audio, connections, misc) and write it with guardrails

• VNyanNet, plugin inventory, native REST/WebSocket/OSC passthroughs

Full capability list and verified behavior: docs/VERIFIED.md.

Requirements

• VNyan, with Allow Mods enabled (Settings → Misc)

• Node.js ≥ 22

• Windows (VNyan itself is Windows-only)

Install

Step 1 — the plugin

1. Download VNyanMcp.dll from the latest release.

2. Close VNyan if it's running.

3. Drop the DLL into <your VNyan folder>\Items\Assemblies\.

4. In VNyan, enable Allow Mods (Settings → Misc) if you haven't already.

5. Start VNyan.

6. Confirm it loaded: open Player.log in VNyan's profile directory (Settings → Misc → Open Log Folder, or %USERPROFILE%\AppData\LocalLow\Suvidriel\VNyan\Player.log by default) and look for [VNyanMcp] initialized.

Step 2 — the MCP server

With Claude Code:

claude mcp add vnyan -- npx -y github:seth-rah/vnyan-mcp

For Claude Desktop or another MCP client, add this to your MCP config:

{
  "mcpServers": {
    "vnyan": {
      "command": "npx",
      "args": ["-y", "github:seth-rah/vnyan-mcp"]
    }
  }
}

No manual build step needed — npx installs and builds it on first run.

Verify

Ask your MCP client to call vnyan_status. All four reflection systems (props, colliders, spout2, stretchbones) should report true, and it will show which VNyan profile directory it resolved and how (see Configuration below — nothing is hardcoded).

Configuration

Every path this server needs is resolved at runtime, not hardcoded. Env vars, all optional:

Security note

The plugin's bridge listens on 127.0.0.1:8071 — loopback-only, but unauthenticated. Any process running as you on your own machine can reach it and drive your avatar while VNyan is running. This is a deliberate tradeoff (matching VNyan's own REST/WS/OSC ports, which have the same property) rather than an oversight, but you should know about it before installing.

What needs VNyan closed

Only settings.json writes (vnyan_settings_set, and the Props/Chains/StretchBones/Gestures/Expressions writes that live inside it) require closing VNyan — it rewrites that file on every save and would silently clobber an external edit. Everything else, including node graph authoring (which exports a file for live import via VNyan's own "Load Graph" menu), works with VNyan running. Details: vnyan_guide topic:'restart-policy'.

Known limits

See docs/VERIFIED.md for the full list. Highlights: post-processing effects and lights are write-only at every tier (no readback exists in VNyan); SunLightNode has an unexplained VNyan-side bug that limits its bridge action to fixed defaults; reflection-backed capabilities (props, colliders, Spout2, stretch bones) depend on internal names that could change in a future VNyan update — vnyan_status is the canary if something breaks.

Building the plugin yourself

cd plugin
dotnet build -c Release -p:VNyanPath="<your VNyan install folder>"

The build fails with a clear error if VNyanPath is missing or doesn't point at a real VNyan install. The bundled node-type schema (src/graph/schema.json) and the reflection-backed capabilities were generated against Unity 2022.3.62f3 — if a VNyan update changes node types or breaks a reflected capability, vnyan_status will show it.

Regenerating the node-type schema

src/graph/schema.json describes all ~300 node types' socket layouts. To regenerate it for a newer VNyan build:

dotnet tool install -g ilspycmd
ilspycmd -p -o /tmp/acs "<your VNyan>/VNyan_Data/Managed/Assembly-CSharp.dll"
python tools/extract-node-schema.py /tmp/acs \
  --unity-version <see Player.log "Initialize engine version"> \
  --graphs "<your VNyan>/Examples/*.json" \
  -o src/graph/schema.json

Passing --graphs matters: node values[] key names can't be read reliably from the obfuscated assembly, so the script prefers names observed in real VNyan-written graph files and flags the rest valuesUncertain.

License

MIT — see LICENSE.