Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/garethbeaumo--originlab-mcp/badge.svg)](/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

i

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.

  1. <p align="center">
  2. <h1 align="center">OriginLab MCP Server</h1>
  3. <p align="center">
  4. <strong>Use AI as your OriginLab assistant</strong>
  5. </p>
  6. <p align="center">
  7. 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>.
  8. </p>
  9. <p align="center">
  10. <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>
  11. <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python">
  12. <img src="https://img.shields.io/badge/version-0.2.1-green.svg" alt="Version">
  13. <img src="https://img.shields.io/badge/platform-Windows-lightgrey.svg" alt="Platform">
  14. <img src="https://img.shields.io/badge/tools-67-orange.svg" alt="Tools">
  15. </p>
  16. <p align="center">
  17. <a href="#quick-start">Quick Start</a> · <a href="#features">Features</a> · <a href="#examples">Examples</a> · <a href="#client-configuration">Client Configuration</a>
  18. </p>
  19. <p align="center">
  20. <a href="README.zh.md">简体中文</a> · English
  21. </p>
  22. </p>
  23. ## What Is OriginLab MCP Server?
  24. 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.
  25. ```text
  26. User: Import experiment.csv from my desktop into Origin, use the first column as X
  27. and the second column as Y, create a scatter plot, run a Gaussian fit,
  28. then export the graph as PNG.
  29. AI: Done.
  30. Imported experiment.csv -> Sheet1 (200 rows x 5 columns)
  31. Created scatter plot -> Graph1
  32. Gaussian fit completed -> xc=2.35, w=0.82, A=156.3, R²=0.9987
  33. Exported -> C:\Users\Desktop\Graph1.png
  34. ```
  35. ### How It Works
  36. ```text
  37. AI Client (Antigravity / Claude / Cursor)
  38. ↓ MCP over stdio
  39. OriginLab MCP Server (Python)
  40. ↓ originpro + COM
  41. OriginLab
  42. ```
  43. ## Requirements
  44. | Requirement | Details |
  45. | :--- | :--- |
  46. | Operating system | Windows |
  47. | OriginLab | OriginLab 2021 or later with a valid license |
  48. | Python | 3.10+ |
  49. ## Quick Start
  50. For AI assistants or one-command local setup, run this from the repository root:
  51. ```powershell
  52. powershell -ExecutionPolicy Bypass -File .\scripts\install-and-open.ps1
  53. ```
  54. 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.
  55. Choose one installation method.
  56. <details open>
  57. <summary><b>Option A: uv (recommended)</b></summary>
  58. **1. Install uv**
  59. ```powershell
  60. irm https://astral.sh/uv/install.ps1 | iex
  61. ```
  62. **2. Install dependencies**
  63. ```powershell
  64. cd C:\path\to\originlab-mcp
  65. uv sync
  66. ```
  67. **3. Start the server**
  68. ```powershell
  69. uv run originlab-mcp
  70. ```
  71. </details>
  72. <details>
  73. <summary><b>Option B: pip</b></summary>
  74. **1. Create a virtual environment (optional but recommended)**
  75. ```powershell
  76. cd C:\path\to\originlab-mcp
  77. python -m venv .venv
  78. .venv\Scripts\activate
  79. ```
  80. **2. Install the project**
  81. ```powershell
  82. pip install -e .
  83. ```
  84. **3. Start the server**
  85. ```powershell
  86. originlab-mcp
  87. ```
  88. </details>
  89. After startup, the server waits for MCP client requests over stdio. The first tool call automatically connects to the local OriginLab installation.
  90. ### Optional: Local Status Panel
  91. To check whether the MCP server can start, whether Origin can be reached, and whether common client config files exist, start the local UI:
  92. ```powershell
  93. uv run originlab-mcp-ui
  94. ```
  95. 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.
  96. When updating an existing config file, the UI creates a `.bak-timestamp` backup first. To prevent the browser from opening automatically:
  97. ```powershell
  98. $env:ORIGINLAB_MCP_UI_NO_BROWSER = "1"
  99. uv run originlab-mcp-ui
  100. ```
  101. ## Features
  102. The server provides **67 tools** covering the OriginLab data workflow.
  103. ### Data Management (14 Tools)
  104. | Category | Tools |
  105. | :--- | :--- |
  106. | Import | `import_csv` · `import_excel` · `import_data_from_text` |
  107. | Inspect | `list_worksheets` · `get_worksheet_info` · `get_worksheet_data` · `get_cell_value` |
  108. | Edit | `set_column_designations` · `set_column_labels` · `set_column_formula` |
  109. | Manage | `add_worksheet` · `sort_worksheet` · `clear_worksheet` · `delete_columns` |
  110. ### Plotting (11 Tools)
  111. | Category | Tools |
  112. | :--- | :--- |
  113. | Create | `create_plot` · `create_double_y_plot` |
  114. | Modify | `add_plot_to_graph` · `remove_plot_from_graph` · `change_plot_data` · `change_plot_type` |
  115. | Layers | `add_graph_layer` · `group_plots` |
  116. | Inspect | `list_graphs` · `list_graph_templates` · `get_graph_info` |
  117. ### Graph Customization (25 Tools)
  118. | Category | Tools |
  119. | :--- | :--- |
  120. | Axes | `set_axis_range` · `set_axis_scale` · `set_axis_step` · `set_axis_title` |
  121. | Lines | `set_plot_line_style` · `set_plot_line_width` |
  122. | Fonts and ticks | `set_graph_font` · `set_tick_style` |
  123. | Colors | `set_plot_color` · `set_plot_colormap` · `set_plot_transparency` |
  124. | Symbols | `set_plot_symbols` · `set_symbol_size` · `set_symbol_interior` |
  125. | Group increments | `set_color_increment` · `set_symbol_increment` |
  126. | Error bars | `set_error_bar_style` |
  127. | Fill | `set_fill_area` |
  128. | Legend | `set_legend` |
  129. | Preset styling | `apply_publication_style` |
  130. | Annotations | `set_graph_title` · `add_text_label` · `add_line_to_graph` · `remove_graph_label` |
  131. ### Analysis (3 Tools)
  132. `linear_fit` · `nonlinear_fit` · `list_fit_functions`
  133. > 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.
  134. ### Export and Project Management (6 Tools)
  135. `export_graph` · `export_all_graphs` · `export_worksheet_to_csv` · `save_project` · `open_project` · `new_project`
  136. ### System Management (6 Tools)
  137. `get_origin_info` · `originlab_doctor` · `read_origin_session` · `release_origin` · `reconnect_origin` · `close_origin`
  138. > `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.
  139. > `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.
  140. ### MCP Resources (Session Reading)
  141. In addition to tools, clients can inspect the Origin session through MCP `resources/read` without changing the project:
  142. | URI | Contents |
  143. | :--- | :--- |
  144. | `originlab://session` | Full project snapshot |
  145. | `originlab://worksheets` | Worksheet list |
  146. | `originlab://graphs` | Graph list |
  147. | `originlab://worksheet/{book}/{sheet}` | One worksheet's columns and data preview |
  148. | `originlab://graph/{name}` | One graph's layers and curves |
  149. ### MCP Prompts (Workflow Templates)
  150. Clients that support `prompts/list` can start common Origin workflows from templates:
  151. | Prompt | Purpose |
  152. | :--- | :--- |
  153. | `originlab_inspect_session` | Read-only session inspection |
  154. | `originlab_csv_to_plot` | CSV → designations → plot → export |
  155. | `originlab_publication_style` | Publication figure styling |
  156. | `originlab_fit_curve` | Linear / nonlinear fitting |
  157. | `originlab_safe_destructive` | Save-first checklist before destructive ops |
  158. ### Advanced (2 Tools)
  159. `execute_labtalk` · `get_labtalk_variable`
  160. `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`.
  161. ### Safety: Preflight Autosave
  162. 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:
  163. | Environment variable | Default | Effect |
  164. | :--- | :--- | :--- |
  165. | `ORIGINLAB_MCP_AUTOSAVE` | on | Set `off` / `false` / `0` to skip preflight saves |
  166. | `ORIGINLAB_MCP_AUTOSAVE_REQUIRED` | off | When on, block the destructive tool if autosave cannot run (no path or save failure) |
  167. | `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) |
  168. 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.
  169. ### Safety: Soft Dispatch Timeout
  170. 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.
  171. | Environment variable | Default | Effect |
  172. | :--- | :--- | :--- |
  173. | `ORIGINLAB_MCP_DISPATCH_TIMEOUT` | `90` | Soft budget in seconds; set `off` / `0` to disable |
  174. `execute_labtalk(..., timeout=120)` overrides the budget for that call only (`0` disables).
  175. ### Safety: Allowed Roots (optional)
  176. 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.
  177. | Environment variable | Default | Effect |
  178. | :--- | :--- | :--- |
  179. | `ORIGINLAB_MCP_ALLOWED_ROOTS` | unset | `os.pathsep`-separated roots (`:` / `;`); commas also accepted |
  180. `get_origin_info` reports the active allowlist as `allowed_roots`.
  181. ## Examples
  182. | Request | Typical tool call |
  183. | :--- | :--- |
  184. | Inspect the current Origin project | `read_origin_session` |
  185. | Import `data.csv` into Origin | `import_csv` |
  186. | Show worksheet columns and metadata | `get_worksheet_info` |
  187. | Set the first column as X and the next two columns as Y | `set_column_designations` |
  188. | Create a scatter plot | `create_plot` |
  189. | Add another curve from the third column | `add_plot_to_graph` |
  190. | Change the X-axis title and set the curve color to red | `set_axis_title` + `set_plot_color` |
  191. | Apply a publication-style preset | `apply_publication_style` |
  192. | Apply publication styling to layer 2 with line width 3 and symbol size 12 | `apply_publication_style` |
  193. | Run a Gaussian fit | `nonlinear_fit` |
  194. | Set the Y axis to logarithmic scale | `set_axis_scale` |
  195. | Export a graph as PNG | `export_graph` |
  196. | Export all project graphs as SVG | `export_all_graphs` |
  197. | Release Origin so I can use it manually | `release_origin` |
  198. `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.
  199. Typical workflow:
  200. ```text
  201. Import data -> inspect structure -> set column designations -> create plot -> customize graph -> run analysis -> export results
  202. ```
  203. ## Client Configuration
  204. > [!NOTE]
  205. > 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.
  206. Replace paths with your actual project path.
  207. 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.
  208. ### Antigravity (Gemini) - Recommended
  209. Create `.gemini/settings.json` in the project root.
  210. **Using uv:**
  211. ```json
  212. {
  213. "mcpServers": {
  214. "originlab": {
  215. "command": "uv",
  216. "args": ["--directory", "C:\\path\\to\\originlab-mcp", "run", "originlab-mcp"]
  217. }
  218. }
  219. }
  220. ```
  221. **Using pip:**
  222. ```json
  223. {
  224. "mcpServers": {
  225. "originlab": {
  226. "command": "C:\\path\\to\\originlab-mcp\\.venv\\Scripts\\originlab-mcp.exe"
  227. }
  228. }
  229. }
  230. ```
  231. <details>
  232. <summary><b>Claude Desktop</b></summary>
  233. Edit `%APPDATA%\Claude\claude_desktop_config.json` using the same format as above.
  234. </details>
  235. <details>
  236. <summary><b>Cursor</b></summary>
  237. Create `.cursor/mcp.json` in the project root using the same format as above.
  238. </details>
  239. <details>
  240. <summary><b>Trae</b></summary>
  241. Create `.trae/mcp.json` in the project root using the same format as above.
  242. </details>
  243. <details>
  244. <summary><b>Codex (OpenAI)</b></summary>
  245. Create `.codex/config.toml` in a trusted project root (Codex uses TOML):
  246. ```toml
  247. [mcp_servers.originlab]
  248. command = "uv"
  249. args = ["--directory", 'C:\path\to\originlab-mcp', "run", "originlab-mcp"]
  250. ```
  251. The status panel preserves other TOML settings and comments and backs up existing files before updating them.
  252. </details>
  253. ## Testing
  254. ```powershell
  255. # uv
  256. uv run python -m pytest tests/ -v
  257. # pip, after activating the virtual environment
  258. pytest tests/ -v
  259. ```
  260. 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.
  261. ## Project Structure
  262. ```text
  263. originlab-mcp/
  264. ├── pyproject.toml # Project configuration and dependencies
  265. ├── CHANGELOG.md # Release notes
  266. ├── .github/workflows/ci.yml # Lint / typecheck / unit tests
  267. ├── scripts/
  268. │ └── install-and-open.ps1 # One-command setup and UI launcher
  269. ├── src/originlab_mcp/
  270. │ ├── server.py # MCP server entry point and dependency injection
  271. │ ├── ui.py # Local status panel
  272. │ ├── origin_manager.py # Thread-safe Origin COM connection manager
  273. │ ├── session.py # Read-only Origin session snapshot
  274. │ ├── resources.py # MCP Resources (session reading)
  275. │ ├── prompts.py # MCP Prompts (workflow templates)
  276. │ ├── exceptions.py # Custom exceptions
  277. │ ├── types.py # Protocol type definitions
  278. │ ├── tools/
  279. │ │ ├── data.py # Data import and worksheet management (14)
  280. │ │ ├── plot.py # Plot creation and graph management (11)
  281. │ │ ├── customize.py # Graph customization (25)
  282. │ │ ├── analysis.py # Linear and nonlinear fitting (3)
  283. │ │ ├── export.py # Export and project management (6)
  284. │ │ ├── system.py # System and connection management (6)
  285. │ │ └── advanced.py # LabTalk escape hatch (2)
  286. │ └── utils/
  287. │ ├── annotations.py # MCP ToolAnnotations presets
  288. │ ├── autosave.py # Preflight autosave policy
  289. │ ├── dispatch.py # Soft COM dispatch timeout
  290. │ ├── doctor.py # originlab_doctor diagnostics
  291. │ ├── paths.py # Allowed-roots path sandbox
  292. │ ├── labtalk_safe.py # LabTalk confirm-gate scanner
  293. │ ├── constants.py # Enums, defaults, and fit-function metadata
  294. │ ├── helpers.py # Graph/sheet resolution and error handling helpers
  295. │ └── validators.py # Input validation and standard response builders
  296. └── tests/
  297. ├── conftest.py # Shared fixtures (manager / fake Origin)
  298. ├── fakes/ # In-memory OriginPro + DummyMCP doubles
  299. ├── test_annotations.py # ToolAnnotations coverage tests
  300. ├── test_autosave.py # Autosave policy / preflight tests
  301. ├── test_dispatch.py # Soft dispatch timeout tests
  302. ├── test_paths.py # Allowed-roots sandbox tests
  303. ├── test_prompts.py # MCP prompt workflow templates
  304. ├── test_doctor.py # originlab_doctor diagnostics
  305. ├── test_origin_contract.py # Multi-tool COM contract workflows
  306. ├── test_tool_guidance.py # Description / next_suggestions contracts
  307. ├── test_helpers.py # Helper tests
  308. ├── test_phase3.py # LabTalk safety and resolve-pattern tests
  309. ├── test_session.py # Session reading and MCP resource tests
  310. ├── test_tools.py # Tool registration and integration tests
  311. └── test_ui.py # Local status panel config tests
  312. ```
  313. ## FAQ
  314. <details>
  315. <summary><b>Origin connection failed</b></summary>
  316. Check that:
  317. - OriginLab 2021 or later is installed locally
  318. - You have a valid OriginLab license
  319. - The current user can start Origin
  320. - No other program is blocking the Origin COM interface
  321. </details>
  322. <details>
  323. <summary><b>The MCP client cannot see the tools</b></summary>
  324. 1. Confirm the client configuration path is correct.
  325. 2. Confirm dependencies are installed with `uv sync` or `pip install -e .`.
  326. 3. Restart the MCP client.
  327. </details>
  328. <details>
  329. <summary><b>Fit results look inaccurate</b></summary>
  330. 1. Check for outliers with `get_worksheet_data`.
  331. 2. Provide better initial values through `initial_params`.
  332. 3. Fix known parameters with `fixed_params`.
  333. 4. Confirm that the fit function is appropriate. Use `list_fit_functions` to inspect common options.
  334. </details>
  335. ## License
  336. [MIT](LICENSE) © 2025 garethbeaumo
  337. For real stdio and Windows + Origin checks, see the [acceptance guide](docs/windows-validation.md) and [evidence-driven follow-up](docs/follow-up.md).
  338. 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 in

Free to use. If it’s helped, pass it on.