HanSur94/matlab-mcp-server-python

Give any AI agent the power of MATLAB — via the Model Context Protocol
Quick Start •
Examples •
Tools Reference •
Configuration •
Wiki
---
A Python MCP server that connects **any AI agent** (Claude, Cursor, Copilot, custom agents) to a shared MATLAB installation. Execute code, discover toolboxes, check code quality, get interactive Plotly plots, and run long simulations — all through MCP.
Why?
- Your AI agent can now **write and run MATLAB code** directly
- **Long-running jobs** (hours!) run async — the agent keeps working while MATLAB computes
- **Multiple users** share one MATLAB server via an elastic engine pool
- **Interactive plots** come back as Plotly JSON — renderable in any web UI
- **Custom MATLAB libraries** become first-class AI tools with zero code changes
Features
| Feature | Description |
|---------|-------------|
| Execute MATLAB code | Sync for fast commands, auto-async for long jobs |
| Elastic engine pool | Scales 2-10+ engines based on demand |
| Toolbox discovery | Browse installed toolboxes, functions, help text |
| Code checker | Run checkcode/mlint before execution |
| Interactive plots | Figures auto-converted to Plotly JSON |
| Multi-user (SSE) | Session isolation with per-user workspaces |
| Custom tools | Expose your .m functions as MCP tools via YAML |
| Progress reporting | Long jobs report percentage back to the agent |
| Cross-platform | Windows + macOS, MATLAB R2022b+ |
| One-click Windows install | Offline install.bat — no admin rights needed |
MATLAB Plot Conversion to Interactive Plotly
Every MATLAB figure is automatically converted into an interactive Plotly chart — no extra code needed. When your MATLAB code creates a plot, the server:
1. **Extracts figure properties** via mcp_extract_props.m — axes, line data, labels, colors, markers, legends, subplots
2. **Maps MATLAB styles to Plotly** — line styles (-- → dash), markers (o → circle), legend positions, axis scales, colormaps
3. **Returns interactive JSON** — renderable in any web UI with Plotly.newPlot()
4. **Generates a static PNG + thumbnail** as fallback for non-interactive clients
**Supported plot types:** line, scatter, bar, area, subplots (subplot/tiledlayout), multiple axes, log/linear scales
**Style fidelity:** Line styles, marker shapes, colors (RGB), line widths, font sizes, axis labels, titles, legends, grid lines, axis limits, and background colors are all preserved.
...automatically becomes this interactive Plotly chart:
Line styles, colors, markers, legends, and axis labels are all preserved in the conversion.
Quick Start
Prerequisites
- **Python 3.10+**
- **MATLAB R2022b+** with the MATLAB Engine API for Python installed
Install the server
**Pixi (recommended, no admin needed):**
Pixi installs Python + all dependencies into an isolated, per-project
environment — no venv wrangling, no admin rights, works the same on Windows/macOS/Linux.
pixi.lock is committed, so pixi run ... always reproduces the exact resolved
environment (Python 3.10–3.12, fastmcp==3.4.4) on any machine — no separate pip install
step needed. matlabengine is deliberately never a static dependency (its sdist build reads
the local MATLAB installation and fails on machines without a matching release); the
install-engine task installs it on demand, matched to your detected MATLAB release.
**Windows (one-click, no admin needed):**
The installer auto-detects MATLAB, creates a virtual environment, and installs everything from bundled wheels — fully offline, no internet required. Works on Windows 10/11 with Python 3.10, 3.11, or 3.12.
**macOS / Linux:**
Run it
With Pixi, the equivalent tasks are pixi run start (stdio), pixi run http
(streamablehttp, preferred), and pixi run sse (legacy alias). streamablehttp is the
transport to reach for on new setups; sse continues to work unchanged so existing