# Mc Iclone8 Mcp

> MCP server for iClone 8: scene creation, transforms, materials, lights, cameras, avatars, facial animation, paths, import/export, diagnostics, and rendering via the official Python API.

- **Type:** MCP server
- **Install:** `agentstack add mcp-gorbabor-mc-iclone8-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gorbabor](https://agentstack.voostack.com/s/gorbabor)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [gorbabor](https://github.com/gorbabor)
- **Source:** https://github.com/gorbabor/mc-iclone8-mcp

## Install

```sh
agentstack add mcp-gorbabor-mc-iclone8-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mc-iclone8-mcp

[Français](README.fr.md)

A local MCP server for controlling iClone 8 through its official Python API.

The iClone plugin provides a small start/stop window. The MCP endpoint is local
only and defaults to `http://127.0.0.1:8766/mcp`. All iClone commands are sent
back to iClone's main thread before they run.

## Requirements

- iClone 8 on Windows.
- A client supporting Streamable HTTP MCP, such as Codex.

## Install the iClone plugin

1. Copy this repository folder to:

   ```text
   \Bin64\OpenPlugin\mc-iclone8-mcp
   ```

2. Start iClone 8 and load the plugin.
3. Open **Plugins → mc-iclone8-mcp → Open MCP server**.
4. Select **Start**. The status must show `http://127.0.0.1:8766/mcp`.

The server deliberately binds to `127.0.0.1`: it is intended for the computer
running iClone, not for a network connection.

## Install as a Codex MCP server

Keep iClone open and start the server first. Then run:

```powershell
codex mcp add mc-iclone8-mcp --url http://127.0.0.1:8766/mcp
```

Restart Codex (or start a new task) after adding it. Confirm the configuration
with:

```powershell
codex mcp list
```

Alternatively, add the following to `%USERPROFILE%\.codex\config.toml` (or to
the project’s `.codex\config.toml`):

```toml
[mcp_servers.mc-iclone8-mcp]
url = "http://127.0.0.1:8766/mcp"
startup_timeout_sec = 15
tool_timeout_sec = 60
```

An identical ready-to-copy sample is available at
[`examples/codex-config.toml`](examples/codex-config.toml).

Configuration examples for Claude Code, Pi coding agent, OpenClaw, Hermes, and
VS Code are collected in [`docs/agent-configs.en.md`](docs/agent-configs.en.md).
The reusable expert skill is available in
[`skills/iclone8-mcp`](skills/iclone8-mcp).

Prompts with scene prerequisites are available in
[`docs/usage-examples.en.md`](docs/usage-examples.en.md) and
[`docs/exemples-utilisation.fr.md`](docs/exemples-utilisation.fr.md).

Detailed setup instructions for Claude Code, Pi coding agent, OpenClaw, Hermes,
and VS Code are available in [`docs/agent-configs.en.md`](docs/agent-configs.en.md)
and [`docs/agent-configs.fr.md`](docs/agent-configs.fr.md).

## Updating the plugin and clients

1. Stop the MCP server with iClone’s **Stop** button.
2. Close or reload the iClone plugin if required by the installed build.
3. Download the new version from the [latest GitHub release](https://github.com/gorbabor/mc-iclone8-mcp/releases).
4. Replace the complete plugin folder:

   ```text
   \Bin64\OpenPlugin\mc-iclone8-mcp
   ```

   Do not mix old files from `tools` with the new release.
5. Restart iClone 8, load the plugin, and click **Start**.
6. Confirm the local URL and restart/reload the MCP client so it refreshes the
   tool list.

The client configurations normally remain unchanged because they continue to
use `http://127.0.0.1:8766/mcp`. Restart the client or MCP session after an
update to avoid a stale tool list. Test new experimental operations in the
installed iClone build before using them on an important scene.

## Available capabilities

The current development line adds the documented iClone 8 camera, material,
light, facial/viseme, content-browser, import, export, and thumbnail operations
to the previous `v0.1.1` baseline. The source registry currently defines 90 MCP
tools; experimental operations must still be checked against the installed
iClone build after restarting the plugin.

| Category | Tools | What they do |
| --- | --- | --- |
| Diagnostics | `ping_iclone`, `get_api_version`, `get_runtime_diagnostics`, `get_application_info`, `list_content_folders`, `list_content_files` | Check connectivity, iClone 8 version/paths, and browse Smart Content folders/files. |
| Scene and objects | `list_objects`, `get_selection`, `select_object`, `set_visibility`, `delete_object`, `clone_object`, `link_object`, `unlink_object`, `align_object`, `set_static` | Inspect, select, show/hide, delete, clone, link, unlink, and align objects. |
| Projects and assets | `create_primitive`, `save_project`, `get_project_info`, `import_asset`, `load_object`, `load_alembic`, `load_motion`, `preload_motion`, `load_substance_painter_textures`, `export_fbx`, `export_obj`, `export_glb`, `save_thumbnail` | Create primitives, import objects/Alembic, load motions, apply textures, save projects, extract thumbnails, and export FBX/OBJ/GLB. OBJ/GLB/Alembic are experimental; OBJ is documented mainly for CC3. |
| Transforms | `get_transform`, `get_object_bounds`, `set_transform`, `delete_transform_key`, `move_transform_key`, `set_transform_key_transition`, `clear_transform_keys` | Read world-space bounds, position, rotation, scale, and animation keys. |
| Paths | `list_paths`, `get_path_info`, `follow_path`, `release_path`, `set_path_position`, `set_path_offset`, `clear_path_keys` | Inspect and control an existing iClone path. Path creation and curve-point editing are not exposed by the public Python API. |
| Timeline | `get_timeline`, `set_timeline`, `play_timeline`, `pause_timeline`, `stop_timeline`, `clear_scene_animations` | Control playback, the playhead, and scene-animation removal. |
| Cameras | `get_camera`, `get_camera_capabilities`, `set_camera`, `set_camera_transform`, `set_camera_focal_key`, `set_camera_dof`, `remove_camera_dof_keys`, `remove_camera_focal_keys`, `set_current_camera`, `set_camera_look_at` | Inspect and animate cameras, set focal length, clipping, depth of field, the active camera, and object tracking. |
| Materials | `get_materials`, `set_material_color`, `set_material_color_channel`, `set_material_texture`, `set_texture_weight`, `set_uv_data`, `load_video_texture`, `set_material_value`, `set_material_attribute` | Inspect materials, animate color channels/UVs/texture weights, load video textures, and change documented tessellation attributes. |
| Lights | `get_light`, `set_light` | Inspect and change activation, color, intensity, range, shadows, spot beam, IES, and rectangular/tube light settings. |
| Avatars | `get_avatar_info`, `get_avatar_capabilities`, `get_skin_bones`, `get_animation_clips`, `set_clip_speed`, `set_clip_loop_count` | Inspect avatars, bones, components, and clips, then set clip speed and looping. |
| Morphs | `list_morphs`, `get_morph_weight`, `set_morph_weight` | List, read, and animate morph weights on compatible props and avatars. |
| Face and voice | `get_face_info`, `set_auto_blink`, `set_face_expressiveness`, `add_expression_keys`, `get_viseme_info`, `add_viseme_key`, `load_vocal` | Inspect and key documented facial expressions/visemes and load vocal audio; these APIs are experimental and may be limited by the iClone build. |
| Rendering | `get_render_settings`, `render_video` | Read the output resolution and start video rendering after explicit confirmation. |
| Mocap and networking | `get_mocap_status`, `get_network_capabilities` | Diagnose the mocap manager and native TCP/UDP availability. |

These tools can be used to:

- inspect, select, transform, show, and remove scene objects;
- create official iClone primitives, import assets, and save projects;
- control the timeline, cameras, and lights;
- inspect and change materials, colors, texture maps, opacity, glossiness, and self-illumination;
- inspect avatar components, skin bones, animation clips, loop counts, and morphs;
- load or pre-load motions, apply Substance Painter texture folders, and export a single object as FBX;
- inspect the current render size and start a render only after explicit confirmation;
- inspect iClone mocap state and native TCP/UDP availability without opening external connections.

The plugin targets iClone 8 exclusively through its official Python API.

## Example instructions for an agent

Give the agent a clear objective, object names, and numeric values. The agent
can inspect the scene first and then call the appropriate MCP tools.

| Category | Example instruction |
| --- | --- |
| Scene | “List the props in the scene, then select `MCP8_Live_Test_Box`.” |
| Creation | “Create a red box named `Logo_Block` at X=0, Y=0, Z=20, and add a floor beneath it.” |
| Transform | “Move `Logo_Block` to X=200 at frame 120 and scale it to 150%.” |
| Materials | “List the materials on `Logo_Block`, then set material 0 to royal blue and hide its diffuse texture.” |
| Texture maps | “Apply `C:\\Assets\\logo_basecolor.png` as the diffuse texture of material 0 on `Logo_Block`.” |
| Material animation | “At frame 300, set `Logo_Block` material 0 opacity to 0.25 and self-illumination to 0.8.” |
| Timeline | “Set the playhead to frame 0, play frames 0 through 300, then stop.” |
| Camera | “Read the active camera's focal length and set it to 50 mm.” |
| Animation | “Animate `Orbit_Sphere` around `Center_Cube` using transform keys at frames 0, 150, 300, 450, and 600.” |
| Avatar | “List the skin bones and animation clips on avatar `Character1`.” |
| Avatar playback | “Inspect `Character1` capabilities, then set clip 0 to loop three times at 1.2× speed.” |
| Morphs | “List the morphs on `Character1`, then set the specified facial morph to weight 0.5 at the current frame.” |
| Import/export | “Import this `.iProp` file, save the project, then export the selected object as FBX.” |
| Render | “Read the render dimensions. Only when I confirm, render the video using the project’s current iClone settings.” |
| Mocap | “Check whether iClone mocap is running; do not change or connect any device.” |

For a camera follow shot, use a real scene camera rather than the iClone
Preview Camera: “Create or activate `Camera1`, then key its transform at the
same frames as the subject, with a consistent relative offset.”

## Development

```powershell
python -m compileall -q .
python -m unittest discover -s tests -v
```

The main technical reference is the official [iClone 8 Python API
documentation](https://wiki.reallusion.com/IC8_Python_API).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gorbabor](https://github.com/gorbabor)
- **Source:** [gorbabor/mc-iclone8-mcp](https://github.com/gorbabor/mc-iclone8-mcp)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-gorbabor-mc-iclone8-mcp
- Seller: https://agentstack.voostack.com/s/gorbabor
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.