ayon-mcp wraps AYON's REST API into six MCP tools — any MCP-compatible agent can browse projects, list folders, and publish texture sets or 3D models with simple tool calls. No raw HTTP, no manual JSON.

Works with Claude Desktop, Cursor, Hermes Agent, and any other MCP client (stdio or HTTP transport).

Tools

Tool	What it does
`ayon_list_projects`	List all AYON projects
`ayon_list_folders`	List folders in a project
`ayon_list_products`	List published products in a folder
`ayon_get_product`	Get product details + latest version
`ayon_publish_texture_set`	Publish multiple texture maps as one product
`ayon_publish_model`	Publish a 3D model (ABC, USD, FBX, ...)

Quick Start

1. Install

pip install git+https://git.niklashmotion.art/Hermes/ayon-mcp.git

2. Configure

Two environment variables required:

Variable	Description
`AYON_URL`	AYON server URL (e.g. `https://ayon.niklashmotion.art`)
`AYON_KEY`	AYON API key from Settings → API Keys

Optional:

Variable	Default	Description
`AYON_TRANSPORT`	`stdio`	`stdio` for Claude/Cursor, `http` for Docker
`PORT`	`8000`	HTTP port (only when `AYON_TRANSPORT=http`)

3a. Use with Claude Desktop / Cursor (stdio)

Add to claude_desktop_config.json or Cursor's MCP config:

{
  "mcpServers": {
    "ayon": {
      "command": "ayon-mcp",
      "env": {
        "AYON_URL": "https://ayon.niklashmotion.art",
        "AYON_KEY": "sk-..."
      }
    }
  }
}

3b. Use with Hermes Agent (stdio)

Add to ~/.hermes/config.yaml:

mcp_servers:
  ayon:
    command: "ayon-mcp"
    env:
      AYON_URL: "https://ayon.niklashmotion.art"
      AYON_KEY: "sk-..."

3c. Docker (HTTP transport)

docker run -d \
  --name ayon-mcp \
  -e AYON_URL=https://ayon.niklashmotion.art \
  -e AYON_KEY=sk-... \
  -e AYON_TRANSPORT=http \
  -p 8000:8000 \
  ghcr.io/niklas/ayon-mcp:latest

Then in Hermes config.yaml:

mcp_servers:
  ayon:
    url: "http://localhost:8000/mcp"
    timeout: 30

3d. Docker Compose

services:
  ayon-mcp:
    build: .
    container_name: mcp-ayon
    environment:
      - AYON_URL=https://ayon.example.com
      - AYON_KEY=sk-...
      - AYON_TRANSPORT=http
    ports:
      - "127.0.0.1:8001:8000"
    restart: unless-stopped

Example: Agent publishes a texture set

User: Publish the chair textures — BaseColor, Roughness, and Normal maps.

Agent calls ayon_publish_texture_set with:
  project: "DemoProject"
  folder_path: "/assets/chair"
  product_name: "texture_chair"
  variant: "wood"
  textures: [
    {"name": "chair_BaseColor.png", "size": 2097152},
    {"name": "chair_Roughness.png", "size": 1048576},
    {"name": "chair_Normal.png", "size": 1572864}
  ]

→ Created product "texture_chair_wood" v1 with 3 texture maps

Architecture

AI Agent (Claude Desktop / Cursor / Hermes)
    │
    │  MCP (stdio or HTTP)
    ▼
ayon-mcp server
    │  X-Api-Key header
    ▼
AYON REST API (/api/projects, /api/products, ...)

The MCP server is the only gatekeeper to AYON. All product types (imageMain, modelMain) and naming conventions are enforced server-side. The AI agent orchestrates the workflow but never touches raw API calls.

Dual transport: stdio + HTTP

stdio (default): AYON_TRANSPORT=stdio or unset. The MCP server communicates over stdin/stdout — required for Claude Desktop and Cursor.
HTTP: AYON_TRANSPORT=http. Listens on PORT (default 8000). Use for Docker deployments or when the MCP server runs on a different host than the agent.

The same binary serves both modes — no separate builds needed.

Compatibility

Feature	AYON ≥1.15	Older AYON
List projects	✅	✅
List folders	✅	✅
Create product	✅	✅
Create version	✅	✅
Create representation	✅	✅
List products (read-back)	⚠️ falls back gracefully	✅
Get last version	⚠️ falls back gracefully	✅

AYON ≥1.15 removed the REST endpoints for listing products and versions. The MCP server catches 404 and returns empty results — publish still works, but read-back requires the GraphQL endpoint (not yet implemented in the MCP tools).

Limitations

REST-only: Products are registered as metadata. Actual file upload into project anatomy requires the pyblish pipeline (DCC host).
No folder creation: Folders must exist before publishing. Use AYON Web UI or Tray Publisher to create them first, or create them via REST API.
Representations are metadata: The files array contains names/sizes, not uploaded content. Full file publishing needs a host with pyblish.

For DCC-integrated publishing (files into anatomy, loadable in Maya/Houdini), combine with ayon-matrix-publish or run inside a DCC host with pyblish.

ayon-matrix-publish — AYON addon that uploads published products to Matrix/Element rooms.
AYON REST API Docs
Hermes MCP Client

README.md

AYON MCP Server