Metadata-Version: 2.5
Name: ovito-mcp
Version: 2026.1
Summary: MCP server for interactive work in OVITO Pro
Project-URL: Homepage, https://www.ovito.org
Project-URL: Documentation, https://docs.ovito.org/reference/data_inspector/coding_agent.html
Project-URL: Repository, https://gitlab.com/ovito-org/ovito-mcp-server
Project-URL: Bug Tracker, https://gitlab.com/ovito-org/ovito-mcp-server/-/issues
Author-email: OVITO GmbH <support@ovito.org>
License: Proprietary
License-File: LICENSE
Keywords: mcp,molecular-dynamics,ovito,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Requires-Dist: jupyter-client>=8.0
Requires-Dist: jupyter-core>=5.0
Requires-Dist: mcp<3,>=2.0
Requires-Dist: numpy>=1.26
Requires-Dist: sentence-transformers>=5.6.0
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# OVITO Pro MCP Server

Connects an AI coding agent to a running **OVITO Pro** session, so you can work with your
simulation data by describing what you want in plain language. The agent operates inside
the session you already have open — it can load files, build and adjust pipelines, analyze
results, and look things up in the OVITO documentation, while you watch each step happen
live in the GUI and keep working in the same window yourself.

Works with Claude Code, GitHub Copilot CLI, OpenAI Codex, OpenCode, Google Antigravity, and
other coding agents that support MCP.

## Requirements

- **OVITO Pro 3.16 or later**, with a valid license
- **Python 3.10 or later**
- A supported coding agent, installed and set up separately (see
  [Agent configuration](#agent-configuration))

## Installation

Install the server:

```sh
pip install ovito-mcp
```

Verify the installation and check the version with:

```sh
ovito-mcp --version
```

The documentation-search tools provided by the OVITO MCP server use two small sentence-transformers models that are downloaded
once from the Hugging Face Hub (~180 MB total) and cached locally. The server downloads them
automatically in the background the first time it starts, and never touches the network for
them again. If you would rather do this one-time download up front — recommended on a slow or
restricted network, so it can't slow down the first search — run:

```sh
ovito-mcp --download-models
```

Then register it with your coding agent, using the **absolute path** to the `ovito-mcp` console
script. For Claude Code:

```powershell
# Windows (PowerShell)
claude mcp add ovito-mcp --scope user -- (Get-Command ovito-mcp).Source
```

```sh
# macOS / Linux
claude mcp add ovito-mcp --scope user -- "$(which ovito-mcp)"
```

See [Agent configuration](#agent-configuration) below for the other agents.

## Using it

In OVITO Pro, open the
[**AI Agent**](https://docs.ovito.org/reference/data_inspector/coding_agent.html) tab in
the data inspector panel at the bottom of the main window, pick your coding agent, and
press **Start**.

OVITO launches the agent and connects it to the session in front of you. Anything the agent
does appears live in the GUI, and you can keep interacting with the same scene while it
works.

No further setup is needed — the agent finds everything it needs from the running OVITO Pro
session.

See the [AI Agent manual page](https://docs.ovito.org/reference/data_inspector/coding_agent.html)
for the OVITO-side documentation, including security considerations.

## Agent configuration

Register `ovito-mcp` by its **absolute path** in the configurations below. Find that path with:

```powershell
# Windows (PowerShell)
(Get-Command ovito-mcp).Source
```

```sh
# macOS / Linux
which ovito-mcp
```

and substitute it for `/path/to/ovito-mcp` in the snippets below.

### Claude Code / Claude Desktop

Add this to your `~/.claude.json`:

```json
"mcpServers": {
  "ovito-mcp": {
    "type": "stdio",
    "command": "/path/to/ovito-mcp"
  }
}
```

### OpenCode

Add this to your `~/.opencode.json`:

```json
"mcp": {
  "ovito-mcp": {
    "type": "local",
    "command": ["/path/to/ovito-mcp"],
    "enabled": true
  }
}
```

### Google Antigravity

Add this to your `~/.antigravity/config.json`:

```json
"mcpServers": {
  "ovito-mcp": {
    "command": "/path/to/ovito-mcp"
  }
}
```

### OpenAI Codex

Add this to your `$HOME/.codex/config.toml`:

```toml
[mcp_servers.ovito-mcp]
command = "/path/to/ovito-mcp"
```

### GitHub Copilot

Add this to your `~/.copilot/mcp-config.json`:

```json
"mcpServers": {
  "ovito-mcp": {
    "command": "/path/to/ovito-mcp"
  }
}
```

## Advanced configuration

Neither setting below is needed for normal use. Both are environment variables, intended
for development and unusual setups.

| Env var        | Purpose                                                                                                                                                                                                       |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OVITO_EXE`    | Path to the OVITO Pro executable (`ovito.exe` on Windows, `ovito` on Linux, `Ovito.app/Contents/MacOS/ovito` on macOS). Only needed to let the agent start OVITO Pro itself, instead of connecting to a session you already have running. |
| `OVITO_RAG_DB` | Path to an alternative documentation database. Overrides the one that ships with OVITO Pro, for developing against a custom build.                                                                            |

## Workflow examples

### Prompt: 

*"Analyze the grain boundary in this sample and highlight repeating structural units in the boundary."*

**Video:** https://www.ovito.org/download/data/videos/ai_agent_demo_gb_analysis.mp4

- Identified the sample as a 2D-periodic bicrystal grain boundary
- Ran structure identification via polyhedral template matching
- Determined the boundary plane, tilt angle, and tilt axis
- Measured periodicity along the boundary with an FFT
- Color-coded the repeating structural units and aligned the camera

### Prompt:

*"Import the ethene molecule and show the electron density along a representative slice — then add bond orders, a colorbar, and color the bonds by particle type."*

**Video:** https://www.ovito.org/download/data/videos/ai_agent_demo_electron_density.mp4

- Loaded the molecule's charge-density file and computed the molecular plane
- Sliced along the plane and aligned the camera to it
- Switched to a logarithmic color scale after spotting oversaturation
- Added a color legend in preview mode
- Computed bond orders and colored bonds to match particle colors

### Prompt:

*"Recreate the analysis and view from this reference figure using my data already loaded in OVITO — don't manipulate the data for better agreement."*

**Video:** https://www.ovito.org/download/data/videos/ai_agent_demo_nano_indentation.mp4

- Identified the sample as SrTiO₃ with a free surface
- Selected the BCC-like cation sublattice for dislocation analysis
- Applied the Dislocation Extraction Algorithm (DXA)
- Matched line and defect-mesh coloring to the reference figure
- Adjusted the camera to match the reference viewport

### Prompt:

*"Read this trajectory and compute the diffusion constant — then plot the result."*

**Video:** https://www.ovito.org/download/data/videos/ai_agent_demo_diffusion.mp4

- Loaded a 1,000-frame trajectory in a 5 Å cubic periodic box
- Unwrapped trajectories to avoid MSD saturation from periodic boundaries
- Computed the mean squared displacement (MSD) over time
- Fit MSD vs. time using the Einstein–Smoluchowski relation
- Plotted the result: D = 0.0490 Å²/ps (R² = 0.995)

## Support

Questions and bug reports: <support@ovito.org>
