Avizo MCP and Codex Skill

Local Model Context Protocol server and Codex skill for Thermo Scientific Amira-Avizo automation on Windows.

This repository is designed as a conservative bridge around an existing local Avizo installation. It does not call private Avizo APIs from outside the Avizo process. Instead, it helps an MCP client:

• discover Avizo, AvizoToGo, Amira, bundled Python, docs, demos, and a job workdir;

• inventory Avizo/Amira project trees containing .hx, .am, .measure.am, TIFF stacks, Header.txt, DVC outputs, and deep-learning artifacts;

• inspect .hx workflows and extract command patterns plus referenced files;

• create reproducible .hx and Python scripts in a job directory;

• generate .pyscro plus .rc script-object skeletons using the public Amira-Avizo extension pattern;

• launch Avizo/AvizoToGo/Amira or run Avizo's bundled Python;

• capture and read job logs.

Repository Layout

src/avizo_mcp/           MCP server package
skills/avizo/            Codex skill that teaches agents how to use the MCP
examples/                Example MCP config and smoke-test scripts
pyproject.toml           Python package metadata

Install

Use standard Windows CPython, not MSYS Python. The mcp dependency pulls pywin32 on Windows, which is not available for MSYS Python builds.

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

Environment

Set these variables in your MCP client config or shell:

$env:AVIZO_HOME = "C:\Program Files\Thermo Scientific Amira-Avizo3D 2024.1"
$env:AVIZO_MCP_WORKDIR = "C:\Users\<you>\Documents\avizo_mcp_jobs"

Optional overrides:

$env:AVIZO_EXE = "C:\Path\To\Avizo3D.exe"
$env:AVIZO_TO_GO_EXE = "C:\Path\To\AvizoToGo.exe"
$env:AMIRA_EXE = "C:\Path\To\Amira3D.exe"
$env:AVIZO_PYTHON_EXE = "C:\Path\To\python.exe"

Run Manually

.\.venv\Scripts\python.exe -m avizo_mcp.server

The server uses stdio transport for MCP clients.

Codex MCP Config

Use examples/codex_mcp_config.toml as a template. Replace paths with your local clone, venv Python, Avizo installation, and job workdir.

Skill

The reusable Codex skill lives at skills/avizo. To install it manually, copy that folder into your Codex skills directory, for example:

Copy-Item -Recurse .\skills\avizo "$env:USERPROFILE\.codex\skills\avizo"

Restart Codex after installing or changing the MCP config.

Safety Notes

• Treat raw CT, .am, and .hx experiment folders as read-only unless a user explicitly asks for in-place edits.

• Generate scripts and logs in AVIZO_MCP_WORKDIR.

• For long Avizo jobs, launch with wait=false and inspect logs before claiming success.

• Review generated .pyscro and .rc files in a disposable AMIRA_LOCAL layout before installing them into a production Avizo setup.

Publishing Notes

Choose an open-source license before publishing this repository. Do not vendor third-party Amira-Avizo automation code unless its license and attribution are handled.