MATLAB MCP Server

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

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.

% This MATLAB code...
x = linspace(0, 2*pi, 200);
plot(x, sin(x), 'r-', 'LineWidth', 2); hold on;
plot(x, cos(x), 'b--', 'LineWidth', 2);
plot(x, sin(x) .* cos(x), 'g-.', 'LineWidth', 2);
legend('sin(x)', 'cos(x)', 'sin(x)*cos(x)');
xlabel('x'); ylabel('y');
title('Trigonometric Functions');

...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 MATLAB Engine API (from your MATLAB installation)
cd /Applications/MATLAB_R2024a.app/extern/engines/python  # macOS
# cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"  # Windows
pip install .

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.

# Install pixi (Windows PowerShell)
irm -useb https://pixi.sh/install.ps1 | iex
# ...or via winget:
winget install prefix-dev.pixi

git clone https://github.com/HanSur94/matlab-mcp-server-python.git
cd matlab-mcp-server-python

# 1. Engine-free start — verifies the server comes up (no MATLAB required yet)
pixi run start

# 2. Detect your local MATLAB install and pip-install the matching matlabengine
pixi run install-engine

# 3. Start again — MATLAB code now actually executes
pixi run start

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):

git clone https://github.com/HanSur94/matlab-mcp-server-python.git
cd matlab-mcp-server-python
install.bat

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:

# Option 1: Install from PyPI
pip install matlab-mcp-python

# Option 2: Install from source
git clone https://github.com/HanSur94/matlab-mcp-server-python.git
cd matlab-mcp-server-python
pip install -e ".[dev]"

Run it

# Single user (stdio) — simplest setup
matlab-mcp

# Multi-user, HTTP — preferred transport (FastMCP 3.4.4 streamable-http)
matlab-mcp --transport streamablehttp

# Multi-user, SSE — legacy alias, kept for existing SSE clients
matlab-mcp --transport sse

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 integrations are never broken.

Connect to Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp"
    }
  }
}

Connect to Claude Code

claude mcp add matlab -- matlab-mcp

Connect to Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp"
    }
  }
}

Run with Docker

# Build the image
docker build -t matlab-mcp .

# Run with your MATLAB mounted
docker run -p 8765:8765 -p 8766:8766 \
  -v /path/to/MATLAB:/opt/matlab:ro \
  -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab \
  matlab-mcp

# Or use docker-compose (edit docker-compose.yml to set your MATLAB path)
docker compose up

Note: The Docker image does not include MATLAB. You must mount your own MATLAB installation.

Upgrading? If you previously installed as matlab-mcp-server, uninstall first: pip uninstall matlab-mcp-server && pip install matlab-mcp-python

Examples

Basic: Run MATLAB Code

Ask your AI agent:

"Calculate the eigenvalues of a 3x3 magic square in MATLAB"

The agent calls execute_code:

A = magic(3);
eigenvalues = eig(A);
disp(eigenvalues)

Result returned inline:

15.0000
 4.8990
-4.8990

Signal Processing

"Generate a 1kHz sine wave, add noise, then filter it with a low-pass Butterworth filter and plot both"

fs = 8000;
t = 0:1/fs:0.1;
clean = sin(2*pi*1000*t);
noisy = clean + 0.5*randn(size(t));

[b, a] = butter(6, 1500/(fs/2));
filtered = filter(b, a, noisy);

subplot(2,1,1); plot(t, noisy); title('Noisy Signal');
subplot(2,1,2); plot(t, filtered); title('Filtered Signal');

Returns: Interactive Plotly chart + static PNG + thumbnail.

Long-Running Simulation (Async)

"Run a Monte Carlo simulation with 1 million trials"

n = 1e6;
results = zeros(n, 1);
for i = 1:n
    results(i) = simulate_trial();  % your custom function
    if mod(i, 1e5) == 0
        mcp_progress(__mcp_job_id__, i/n*100, sprintf('Trial %d/%d', i, n));
    end
end
disp(mean(results));

The agent gets a job ID immediately, polls progress ("Trial 500000/1000000 — 50%"), and retrieves results when done.

Custom Tools

Expose your proprietary MATLAB functions as first-class AI tools. Create custom_tools.yaml: