originlab-mcp
MCP Server for OriginLab Control OriginLab with natural language through AI clients via the Model Context Protocol.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/garethbeaumo--originlab-mcp)HTML
<a href="/listings/garethbeaumo--originlab-mcp"><img src="/api/listings/garethbeaumo--originlab-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
For AI assistants or one-command local setup, run this from the repository root:
powershell -ExecutionPolicy Bypass -File .\scripts\install-and-open.ps1
The script installs `uv` if needed, runs `uv sync`, starts the local status panel, and opens `http://127.0.0.1:8765/` automatically. From that page you can test Origin and write MCP client configs.
Choose one installation method.
<details open> <summary><b>Option A: uv (recommended)</b></summary>
**1. Install uv**
irm https://astral.sh/uv/install.ps1 | iex
**2. Install dependencies**
cd C:\path\to\originlab-mcp uv sync
**3. Start the server**
uv run originlab-mcp
</details>
<details> <summary><b>Option B: pip</b></summary>
**1. Create a virtual environment (optional but recommended)**
cd C:\path\to\originlab-mcp python -m venv .venv .venv\Scripts\activate
**2. Install the project**
pip install -e .
**3. Start the server**
originlab-mcp
</details>
After startup, the server waits for MCP client requests over stdio. The first tool call automatically connects to the local OriginLab installation.
Optional: Local Status Panel
To check whether the MCP server can start, whether Origin can be reached, and whether common client config files exist, start the local UI:
uv run originlab-mcp-ui
Then open `http://127.0.0.1:8765/`. This page can start/stop a debug MCP server subprocess, test the Origin connection, **read the current Origin session** (worksheets and graphs), and write the `originlab` MCP configuration for Antigravity / Gemini, Cursor, Codex, Trae, and Claude Desktop. For normal use, the AI client should still start the server automatically from its configuration.
When updating an existing config file, the UI creates a `.bak-timestamp` backup first. To prevent the browser from opening automatically:
$env:ORIGINLAB_MCP_UI_NO_BROWSER = "1" uv run originlab-mcp-ui
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 462 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <p align="center">
- <h1 align="center">OriginLab MCP Server</h1>
- <p align="center">
- <strong>Use AI as your OriginLab assistant</strong>
- </p>
- <p align="center">
- Connect OriginLab data analysis and visualization to Antigravity, Claude, Cursor, and other AI clients through the <a href="https://modelcontextprotocol.io">Model Context Protocol</a>.
- </p>
- <p align="center">
- <a href="https://github.com/garethbeaumo/originlab-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
- <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python">
- <img src="https://img.shields.io/badge/version-0.2.1-green.svg" alt="Version">
- <img src="https://img.shields.io/badge/platform-Windows-lightgrey.svg" alt="Platform">
- <img src="https://img.shields.io/badge/tools-67-orange.svg" alt="Tools">
- </p>
- <p align="center">
- <a href="#quick-start">Quick Start</a> · <a href="#features">Features</a> · <a href="#examples">Examples</a> · <a href="#client-configuration">Client Configuration</a>
- </p>
- <p align="center">
- <a href="README.zh.md">简体中文</a> · English
- </p>
- </p>
- ## What Is OriginLab MCP Server?
- OriginLab MCP Server is a bridge between AI clients and OriginLab. It lets you import data, create plots, customize figures, run analysis, and export results through natural-language requests instead of manually operating the Origin UI.
- ```text
- User: Import experiment.csv from my desktop into Origin, use the first column as X
- and the second column as Y, create a scatter plot, run a Gaussian fit,
- then export the graph as PNG.
- AI: Done.
- Imported experiment.csv -> Sheet1 (200 rows x 5 columns)
- Created scatter plot -> Graph1
- Gaussian fit completed -> xc=2.35, w=0.82, A=156.3, R²=0.9987
- Exported -> C:\Users\Desktop\Graph1.png
- ```
- ### How It Works
- ```text
- AI Client (Antigravity / Claude / Cursor)
- ↓ MCP over stdio
- OriginLab MCP Server (Python)
- ↓ originpro + COM
- OriginLab
- ```
- ## Requirements
- | Requirement | Details |
- | :--- | :--- |
- | Operating system | Windows |
- | OriginLab | OriginLab 2021 or later with a valid license |
- | Python | 3.10+ |
- ## Quick Start
- For AI assistants or one-command local setup, run this from the repository root:
- ```powershell
- powershell -ExecutionPolicy Bypass -File .\scripts\install-and-open.ps1
- ```
- The script installs `uv` if needed, runs `uv sync`, starts the local status panel, and opens `http://127.0.0.1:8765/` automatically. From that page you can test Origin and write MCP client configs.
- Choose one installation method.
- <details open>
- <summary><b>Option A: uv (recommended)</b></summary>
- **1. Install uv**
- ```powershell
- irm https://astral.sh/uv/install.ps1 | iex
- ```
- **2. Install dependencies**
- ```powershell
- cd C:\path\to\originlab-mcp
- uv sync
- ```
- **3. Start the server**
- ```powershell
- uv run originlab-mcp
- ```
- </details>
- <details>
- <summary><b>Option B: pip</b></summary>
- **1. Create a virtual environment (optional but recommended)**
- ```powershell
- cd C:\path\to\originlab-mcp
- python -m venv .venv
- .venv\Scripts\activate
- ```
- **2. Install the project**
- ```powershell
- pip install -e .
- ```
- **3. Start the server**
- ```powershell
- originlab-mcp
- ```
- </details>
- After startup, the server waits for MCP client requests over stdio. The first tool call automatically connects to the local OriginLab installation.
- ### Optional: Local Status Panel
- To check whether the MCP server can start, whether Origin can be reached, and whether common client config files exist, start the local UI:
- ```powershell
- uv run originlab-mcp-ui
- ```
- Then open `http://127.0.0.1:8765/`. This page can start/stop a debug MCP server subprocess, test the Origin connection, **read the current Origin session** (worksheets and graphs), and write the `originlab` MCP configuration for Antigravity / Gemini, Cursor, Codex, Trae, and Claude Desktop. For normal use, the AI client should still start the server automatically from its configuration.
- When updating an existing config file, the UI creates a `.bak-timestamp` backup first. To prevent the browser from opening automatically:
- ```powershell
- $env:ORIGINLAB_MCP_UI_NO_BROWSER = "1"
- uv run originlab-mcp-ui
- ```
- ## Features
- The server provides **67 tools** covering the OriginLab data workflow.
- ### Data Management (14 Tools)
- | Category | Tools |
- | :--- | :--- |
- | Import | `import_csv` · `import_excel` · `import_data_from_text` |
- | Inspect | `list_worksheets` · `get_worksheet_info` · `get_worksheet_data` · `get_cell_value` |
- | Edit | `set_column_designations` · `set_column_labels` · `set_column_formula` |
- | Manage | `add_worksheet` · `sort_worksheet` · `clear_worksheet` · `delete_columns` |
- ### Plotting (11 Tools)
- | Category | Tools |
- | :--- | :--- |
- | Create | `create_plot` · `create_double_y_plot` |
- | Modify | `add_plot_to_graph` · `remove_plot_from_graph` · `change_plot_data` · `change_plot_type` |
- | Layers | `add_graph_layer` · `group_plots` |
- | Inspect | `list_graphs` · `list_graph_templates` · `get_graph_info` |
- ### Graph Customization (25 Tools)
- | Category | Tools |
- | :--- | :--- |
- | Axes | `set_axis_range` · `set_axis_scale` · `set_axis_step` · `set_axis_title` |
- | Lines | `set_plot_line_style` · `set_plot_line_width` |
- | Fonts and ticks | `set_graph_font` · `set_tick_style` |
- | Colors | `set_plot_color` · `set_plot_colormap` · `set_plot_transparency` |
- | Symbols | `set_plot_symbols` · `set_symbol_size` · `set_symbol_interior` |
- | Group increments | `set_color_increment` · `set_symbol_increment` |
- | Error bars | `set_error_bar_style` |
- | Fill | `set_fill_area` |
- | Legend | `set_legend` |
- | Preset styling | `apply_publication_style` |
- | Annotations | `set_graph_title` · `add_text_label` · `add_line_to_graph` · `remove_graph_label` |
- ### Analysis (3 Tools)
- `linear_fit` · `nonlinear_fit` · `list_fit_functions`
- > Common Origin fit functions such as Gauss, Lorentz, ExpDec1, and Boltzmann are supported. You can provide initial parameters, fix parameters, and fit with error bars.
- ### Export and Project Management (6 Tools)
- `export_graph` · `export_all_graphs` · `export_worksheet_to_csv` · `save_project` · `open_project` · `new_project`
- ### System Management (6 Tools)
- `get_origin_info` · `originlab_doctor` · `read_origin_session` · `release_origin` · `reconnect_origin` · `close_origin`
- > `originlab_doctor` is a read-only environment checklist (platform, originpro, autosave / dispatch / allowed-roots policy). Pass `ping_origin=true` to attempt a live Origin connect.
- > `read_origin_session` is a read-only snapshot of the current project: workbooks/worksheets, graphs, matrices, notes, active objects, and project path. Pass `include_preview=true` to include a truncated preview of the active worksheet.
- ### MCP Resources (Session Reading)
- In addition to tools, clients can inspect the Origin session through MCP `resources/read` without changing the project:
- | URI | Contents |
- | :--- | :--- |
- | `originlab://session` | Full project snapshot |
- | `originlab://worksheets` | Worksheet list |
- | `originlab://graphs` | Graph list |
- | `originlab://worksheet/{book}/{sheet}` | One worksheet's columns and data preview |
- | `originlab://graph/{name}` | One graph's layers and curves |
- ### MCP Prompts (Workflow Templates)
- Clients that support `prompts/list` can start common Origin workflows from templates:
- | Prompt | Purpose |
- | :--- | :--- |
- | `originlab_inspect_session` | Read-only session inspection |
- | `originlab_csv_to_plot` | CSV → designations → plot → export |
- | `originlab_publication_style` | Publication figure styling |
- | `originlab_fit_curve` | Linear / nonlinear fitting |
- | `originlab_safe_destructive` | Save-first checklist before destructive ops |
- ### Advanced (2 Tools)
- `execute_labtalk` · `get_labtalk_variable`
- `execute_labtalk` is an escape hatch for operations not covered by standard tools. `get_labtalk_variable` safely reads LabTalk variable values. Destructive LabTalk (delete / `doc -n` / `win -c`, etc.) requires `confirm=true`.
- ### Safety: Preflight Autosave
- Before destructive tools (`new_project`, `open_project`, `clear_worksheet`, `delete_columns`, `remove_plot_from_graph`, `remove_graph_label`, `close_origin`, and confirmed destructive LabTalk), the server attempts an in-place project save when a project path is known:
- | Environment variable | Default | Effect |
- | :--- | :--- | :--- |
- | `ORIGINLAB_MCP_AUTOSAVE` | on | Set `off` / `false` / `0` to skip preflight saves |
- | `ORIGINLAB_MCP_AUTOSAVE_REQUIRED` | off | When on, block the destructive tool if autosave cannot run (no path or save failure) |
- | `ORIGINLAB_MCP_AUTOSAVE_INTERVAL` | `300` | Also save in place every N seconds when a project path is known; `off` / `0` disables periodic saves (preflight still runs) |
- Save explicitly with `save_project(file_path=...)`. Implicit saves and autosave now require a unique, full project path from the live session; cached destinations are never reused after a manual project switch or reconnect. Missing or ambiguous metadata skips autosave and blocks destructive operations in required mode. Some Origin versions may not expose the currently supported path metadata; use an explicit save path and record the result in the [Windows acceptance checklist](docs/windows-validation.md). In-place saving overwrites the file and is not a versioned backup. Preflight save and the following mutation are not yet an atomic transaction.
- ### Safety: Soft Dispatch Timeout
- Each COM-backed tool call has a soft wall-clock budget (default **90s**). If Origin does not return in time — often because a modal dialog is open — the server raises a structured `timeout` error **without** killing Origin. The underlying COM call may still be running and will hold the lock until Origin unblocks.
- | Environment variable | Default | Effect |
- | :--- | :--- | :--- |
- | `ORIGINLAB_MCP_DISPATCH_TIMEOUT` | `90` | Soft budget in seconds; set `off` / `0` to disable |
- `execute_labtalk(..., timeout=120)` overrides the budget for that call only (`0` disables).
- ### Safety: Allowed Roots (optional)
- When set, all import / export / save / open file paths must resolve under one of the allowed directories (path traversal via `..` is rejected). Unset keeps unrestricted access for typical desktop Origin workflows.
- | Environment variable | Default | Effect |
- | :--- | :--- | :--- |
- | `ORIGINLAB_MCP_ALLOWED_ROOTS` | unset | `os.pathsep`-separated roots (`:` / `;`); commas also accepted |
- `get_origin_info` reports the active allowlist as `allowed_roots`.
- ## Examples
- | Request | Typical tool call |
- | :--- | :--- |
- | Inspect the current Origin project | `read_origin_session` |
- | Import `data.csv` into Origin | `import_csv` |
- | Show worksheet columns and metadata | `get_worksheet_info` |
- | Set the first column as X and the next two columns as Y | `set_column_designations` |
- | Create a scatter plot | `create_plot` |
- | Add another curve from the third column | `add_plot_to_graph` |
- | Change the X-axis title and set the curve color to red | `set_axis_title` + `set_plot_color` |
- | Apply a publication-style preset | `apply_publication_style` |
- | Apply publication styling to layer 2 with line width 3 and symbol size 12 | `apply_publication_style` |
- | Run a Gaussian fit | `nonlinear_fit` |
- | Set the Y axis to logarithmic scale | `set_axis_scale` |
- | Export a graph as PNG | `export_graph` |
- | Export all project graphs as SVG | `export_all_graphs` |
- | Release Origin so I can use it manually | `release_origin` |
- `apply_publication_style` supports `layer_index`, axis-title font size, tick-label font size, legend font size, major tick length, minor tick count, line width, symbol size, and other common publication-figure settings.
- Typical workflow:
- ```text
- Import data -> inspect structure -> set column designations -> create plot -> customize graph -> run analysis -> export results
- ```
- ## Client Configuration
- > [!NOTE]
- > You do not need to start the MCP server manually. Once configured, the AI client starts the server process when needed and communicates with it over stdin/stdout.
- Replace paths with your actual project path.
- You can also run `uv run originlab-mcp-ui`, choose a client in the local status panel, and let it write the config automatically. Manual examples are shown below.
- ### Antigravity (Gemini) - Recommended
- Create `.gemini/settings.json` in the project root.
- **Using uv:**
- ```json
- {
- "mcpServers": {
- "originlab": {
- "command": "uv",
- "args": ["--directory", "C:\\path\\to\\originlab-mcp", "run", "originlab-mcp"]
- }
- }
- }
- ```
- **Using pip:**
- ```json
- {
- "mcpServers": {
- "originlab": {
- "command": "C:\\path\\to\\originlab-mcp\\.venv\\Scripts\\originlab-mcp.exe"
- }
- }
- }
- ```
- <details>
- <summary><b>Claude Desktop</b></summary>
- Edit `%APPDATA%\Claude\claude_desktop_config.json` using the same format as above.
- </details>
- <details>
- <summary><b>Cursor</b></summary>
- Create `.cursor/mcp.json` in the project root using the same format as above.
- </details>
- <details>
- <summary><b>Trae</b></summary>
- Create `.trae/mcp.json` in the project root using the same format as above.
- </details>
- <details>
- <summary><b>Codex (OpenAI)</b></summary>
- Create `.codex/config.toml` in a trusted project root (Codex uses TOML):
- ```toml
- [mcp_servers.originlab]
- command = "uv"
- args = ["--directory", 'C:\path\to\originlab-mcp', "run", "originlab-mcp"]
- ```
- The status panel preserves other TOML settings and comments and backs up existing files before updating them.
- </details>
- ## Testing
- ```powershell
- # uv
- uv run python -m pytest tests/ -v
- # pip, after activating the virtual environment
- pytest tests/ -v
- ```
- The basic test suite does not require OriginLab to be installed. On Linux/macOS, `originpro` is skipped automatically because it is marked Windows-only in `pyproject.toml`. GitHub Actions runs ruff, mypy, and pytest (with coverage XML) on Python 3.10–3.12.
- ## Project Structure
- ```text
- originlab-mcp/
- ├── pyproject.toml # Project configuration and dependencies
- ├── CHANGELOG.md # Release notes
- ├── .github/workflows/ci.yml # Lint / typecheck / unit tests
- ├── scripts/
- │ └── install-and-open.ps1 # One-command setup and UI launcher
- ├── src/originlab_mcp/
- │ ├── server.py # MCP server entry point and dependency injection
- │ ├── ui.py # Local status panel
- │ ├── origin_manager.py # Thread-safe Origin COM connection manager
- │ ├── session.py # Read-only Origin session snapshot
- │ ├── resources.py # MCP Resources (session reading)
- │ ├── prompts.py # MCP Prompts (workflow templates)
- │ ├── exceptions.py # Custom exceptions
- │ ├── types.py # Protocol type definitions
- │ ├── tools/
- │ │ ├── data.py # Data import and worksheet management (14)
- │ │ ├── plot.py # Plot creation and graph management (11)
- │ │ ├── customize.py # Graph customization (25)
- │ │ ├── analysis.py # Linear and nonlinear fitting (3)
- │ │ ├── export.py # Export and project management (6)
- │ │ ├── system.py # System and connection management (6)
- │ │ └── advanced.py # LabTalk escape hatch (2)
- │ └── utils/
- │ ├── annotations.py # MCP ToolAnnotations presets
- │ ├── autosave.py # Preflight autosave policy
- │ ├── dispatch.py # Soft COM dispatch timeout
- │ ├── doctor.py # originlab_doctor diagnostics
- │ ├── paths.py # Allowed-roots path sandbox
- │ ├── labtalk_safe.py # LabTalk confirm-gate scanner
- │ ├── constants.py # Enums, defaults, and fit-function metadata
- │ ├── helpers.py # Graph/sheet resolution and error handling helpers
- │ └── validators.py # Input validation and standard response builders
- └── tests/
- ├── conftest.py # Shared fixtures (manager / fake Origin)
- ├── fakes/ # In-memory OriginPro + DummyMCP doubles
- ├── test_annotations.py # ToolAnnotations coverage tests
- ├── test_autosave.py # Autosave policy / preflight tests
- ├── test_dispatch.py # Soft dispatch timeout tests
- ├── test_paths.py # Allowed-roots sandbox tests
- ├── test_prompts.py # MCP prompt workflow templates
- ├── test_doctor.py # originlab_doctor diagnostics
- ├── test_origin_contract.py # Multi-tool COM contract workflows
- ├── test_tool_guidance.py # Description / next_suggestions contracts
- ├── test_helpers.py # Helper tests
- ├── test_phase3.py # LabTalk safety and resolve-pattern tests
- ├── test_session.py # Session reading and MCP resource tests
- ├── test_tools.py # Tool registration and integration tests
- └── test_ui.py # Local status panel config tests
- ```
- ## FAQ
- <details>
- <summary><b>Origin connection failed</b></summary>
- Check that:
- - OriginLab 2021 or later is installed locally
- - You have a valid OriginLab license
- - The current user can start Origin
- - No other program is blocking the Origin COM interface
- </details>
- <details>
- <summary><b>The MCP client cannot see the tools</b></summary>
- 1. Confirm the client configuration path is correct.
- 2. Confirm dependencies are installed with `uv sync` or `pip install -e .`.
- 3. Restart the MCP client.
- </details>
- <details>
- <summary><b>Fit results look inaccurate</b></summary>
- 1. Check for outliers with `get_worksheet_data`.
- 2. Provide better initial values through `initial_params`.
- 3. Fix known parameters with `fixed_params`.
- 4. Confirm that the fit function is appropriate. Use `list_fit_functions` to inspect common options.
- </details>
- ## License
- [MIT](LICENSE) © 2025 garethbeaumo
- For real stdio and Windows + Origin checks, see the [acceptance guide](docs/windows-validation.md) and [evidence-driven follow-up](docs/follow-up.md).
- Queued calls whose budget expires before acquiring the COM lock never execute; already-started calls may still finish after a soft timeout.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.