@mixio-pro/mcp

small local helper that lets AI assistants (Claude Desktop, Cursor, Claude Code,...) work with files on your computer and Mixio Studio at same time.

It does two things:

1. Caches your files. When you ask assistant to use local file (video, image, audio clip, script, etc.), this helper uploads it to Mixio Studio once and remembers URL. Next time you reference same file, no re-upload. If file changed, it auto-uploads again.
2. Connects to your Studio account. assistant gets all of your Mixio Studio tools — projects, scenes, elements, generations — through one local entry point.

Quick install

You need:

• Node.js 22 or newer (most modern Macs and Windows have this).
• Mixio Studio API key. Get it from your Studio settings → API keys.

Add this to your AI assistant's MCP config (one of ~/.claude/claude_desktop_config.json, ~/.cursor/mcp.json, project-level .mcp.json, etc.):

{
  "mcpServers": {
    "mixio": {
      "command": "npx",
      "args": ["-y", "@mixio-pro/mcp"],
      "env": {
        "MIXIO_API_KEY": "sk-…paste-your-key-here…"
      }
    }
  }
}

Restart assistant and you're done. No build step, no install, paste and go.

What you get

Once it's running, your assistant has these tools:

| Tool | What it does | | --- | --- | | upload_file | Upload a local file. Hash-aware, so calling it twice on the same file uses the cache. | | get_public_url | Get the Mixio URL for any local file. Auto-uploads on first call. | | list_cached_files | See everything cached so far. | | forget_path / clear_cache | Drop a single entry or wipe the cache. | | register_asset | Register an uploaded asset under a project so it's referenceable in evaluations via an @alias. | | run_evaluation | Submit a visual continuity / consistency evaluation job. | | get_evaluation_result | Poll or retrieve the status and results of a background evaluation. | | list_projects | List production review projects. | | studio_* | All 25+ Studio MCP tools (create projects, list scenes, generate, etc.). |

How file caching works

• Each file is hashed (SHA-256) on first use.
• mapping local path ↔ hash ↔ Mixio URL is stored in small SQLite database at ~/.mixio/mcp-cache.db.
• Two different paths to same content reuse one upload (deduped by hash).
• Edit file in place? cache notices on next call and re-uploads.
• Multiple sessions can share cache safely (WAL mode, multi-process safe).

Configuration

All optional. Defaults work for most people.

| Variable | Default | What it does | | --- | --- | --- | | MIXIO_API_KEY | — (required) | Your Studio API key. | | MIXIO_BASE_URL | https://studio.mixio.pro | Studio URL. Override for staging or self-hosted. | | MIXIO_HOME | ~/.mixio | Where the cache lives. | | MIXIO_FASTMCP_CACHE | ${MIXIO_HOME}/mcp-cache.db | Override cache path. | | MIXIO_FASTMCP_TIMEOUT_MS | 60000 | HTTP timeout for non-upload calls. | | MIXIO_FASTMCP_UPLOAD_TIMEOUT_MS | 300000 | Upload timeout. | | MIXIO_FASTMCP_UPSTREAM_CONNECT_TIMEOUT_MS | 10000 | How long to wait for Studio MCP at startup. |

Running from source (developers)

git clone <this-repo>
cd packages/mcp
pnpm install
pnpm build
MIXIO_API_KEY=sk-… node dist/bin.js

Tests: pnpm test. There are 35 of them covering cross-OS path handling, multi-process cache concurrency, drift detection, and end-to-end stdio.

License

MIT. See LICENSE.