MohoMCP

An MCP (Model Context Protocol) server for Moho Pro 14 — enabling AI assistants like Claude Desktop and Claude Code to read, write, animate, and visually operate MOHO animation projects.

Fully cross-platform: Windows and macOS.

┌─────────────────────┐    File-based IPC     ┌──────────────────────┐
│  MCP Bridge Server  │◄──────────────────►   │  Moho Lua Plugin     │
│  (TypeScript/Node)  │  $TMPDIR/moho-mcp/    │  (runs inside MOHO)  │
└────────┬────────────┘   JSON-RPC 2.0        └──────────────────────┘
         │ MCP Protocol (stdio)
┌────────▼────────────┐
│  MCP Client/Host    │
│  (Claude Desktop,   │
│   Claude Code, etc) │
└─────────────────────┘

Three components:

1. Moho Lua Plugin — File-based IPC server running inside MOHO, handles read/write operations via MOHO's Lua 5.4 API
2. MCP Bridge Server — Node.js process bridging MCP protocol (stdio) to file-based JSON-RPC
3. Static Knowledge Resources — Keyboard shortcuts and tool reference data from the Moho manual

Performance tip: Always prefer batch_execute when you need 2+ operations. A batch of 10 operations takes the same time as 1 individual call.

Copy the moho-plugin/ contents into MOHO's scripts folder, or use the provided install scripts:

Windows: Run install-plugin.bat (or copy manually to C:\Program Files\Moho 14\Resources\Support\Scripts\Menu\)

macOS: Run chmod +x install-plugin.sh && ./install-plugin.sh (or copy manually to /Applications/Moho 14/Moho Pro.app/Contents/Resources/Support/Scripts/Menu/)

Files to copy:

• MohoMCP_Server.lua
• MohoMCP_Poller.lua
• json.lua
• moho_mcp/ (entire directory)

cd bridge
npm install
npm run build

1. Open Moho Pro 14 and load a project
2. Go to Scripts > MohoMCP Server to start the IPC server
3. Start your MCP client (Claude Desktop or Claude Code) — the bridge auto-connects

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "moho-mcp": {
      "command": "node",
      "args": ["C:/path/to/MohoMCP/bridge/dist/index.js"]
    }
  }
}

Place a .mcp.json in your project root:

{
  "mcpServers": {
    "moho-mcp": {
      "command": "node",
      "args": ["C:/path/to/MohoMCP/bridge/dist/index.js"]
    }
  }
}

Environment variables:

Internal timing (in bridge/src/config.ts):

Communication uses JSON files in the system temp directory (%TEMP%\moho-mcp\ on Windows, $TMPDIR/moho-mcp/ on macOS):

1. Bridge writes req_<id>.json (JSON-RPC 2.0 request)
2. MOHO Lua plugin polls for request files via DrawMe/IsEnabled callbacks
3. Lua processes the request, writes resp_<id>.json
4. Bridge reads the response, cleans up files

MOHO only processes Lua callbacks during UI repaints. A background process periodically forces viewport redraws (~4 Hz) to keep the polling loop alive even when the user isn't interacting:

• Windows: PowerShell process calling Win32 RedrawWindow()
• macOS: AppleScript process nudging the Moho application

• Allow-list validation: Only explicitly registered methods can be called
• Parameter validation: All parameters type-checked before execution
• pcall wrapping: All Lua handlers wrapped in protected calls — a crash in one method won't crash the server

cd bridge
npm install
npm run dev      # Watch mode — recompiles on changes
npm test         # Run test suite (61 tests)
npm run test:watch

MohoMCP/
├── bridge/                    # TypeScript MCP Bridge Server
│   └── src/
│       ├── index.ts           # Entry point & bootstrap
│       ├── config.ts          # IPC directory, timeouts
│       ├── moho-client.ts     # File-based IPC client
│       ├── protocol.ts        # JSON-RPC 2.0 types
│       ├── tools.ts           # 26 MCP tool registrations
│       ├── resources.ts       # Static knowledge resources
│       ├── keep-alive.ts      # Cross-platform viewport refresh
│       ├── platform-capture.ts # Platform dispatch → window capture
│       ├── platform-input.ts  # Platform dispatch → input simulation
│       ├── window-capture.ts  # Win32 screenshot capture
│       ├── darwin-capture.ts  # macOS screenshot capture
│       ├── win32-input.ts     # Win32 mouse & keyboard
│       ├── darwin-input.ts    # macOS mouse & keyboard
│       └── __tests__/         # Vitest test suite
│
├── moho-plugin/               # Lua Plugin for MOHO 14
│   ├── MohoMCP_Server.lua     # Menu script & DrawMe hooks
│   ├── MohoMCP_Poller.lua     # Polling utilities
│   ├── json.lua               # JSON library
│   └── moho_mcp/
│       ├── server.lua         # File-based IPC server
│       ├── protocol.lua       # JSON-RPC 2.0 protocol
│       ├── validator.lua      # Method allow-list & validation
│       └── tools/             # Handler implementations
│           ├── document.lua
│           ├── layer.lua
│           ├── bone.lua
│           ├── animation.lua
│           ├── mesh.lua
│           └── batch.lua
│
├── docs/                      # Documentation
│   ├── installation.md
│   └── tool-reference.md
│
└── schema/
    └── tools.json             # JSON Schema definitions

All 26 tools work identically on both platforms. The bridge auto-detects the OS at runtime and loads the appropriate native backend — no configuration needed.

• Windows 10/11
• Moho Pro 14
• Node.js >= 18.0.0

• macOS (tested on Ventura+)
• Moho Pro 14
• Node.js >= 18.0.0
• Accessibility permissions — required for input simulation (System Settings > Privacy & Security > Accessibility > add your terminal / Claude Desktop)
• cliclick (optional, recommended) — brew install cliclick — provides more reliable mouse input. Without it, falls back to CoreGraphics via JXA.

MIT — see LICENSE for details.