Skip to content

FAQ

Jump to bottom
github-actions[bot] edited this page Mar 22, 2026 · 20 revisions

FAQ

General

What MATLAB versions are supported?

MATLAB R2022b and later. The MATLAB Engine API for Python must be installed separately from your MATLAB installation.

Does it work without MATLAB installed?

No. The server requires a local MATLAB installation with the Engine API. It connects to real MATLAB engines, not a simulator.

Can I use it with MATLAB Online?

Not currently. The server connects to locally-installed MATLAB via the Engine API, which requires a local installation.

What AI agents work with this?

Any agent that supports the Model Context Protocol (MCP): Claude Desktop, Claude Code, Cursor, GitHub Copilot (with MCP support), and custom agents built with MCP SDKs.

Can I install it from PyPI?

Yes:

pip install matlab-mcp-python

You still need to install the MATLAB Engine API separately from your MATLAB installation. See the README for installation details.

Can I run it in Docker?

Yes. The project includes a Dockerfile and docker-compose.yml. The Docker image does not include MATLAB — you must mount your own MATLAB installation as a volume. See the README for Docker setup instructions.

Is there a Windows installer?

Yes. Run install.bat for a one-click Windows installer that works offline, requires no admin rights, and auto-detects your MATLAB installation. Works on Windows 10/11 with Python 3.10, 3.11, or 3.12.

Setup

How do I install the MATLAB Engine API?

cd /Applications/MATLAB_R2024a.app/extern/engines/python  # macOS
# cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"  # Windows
pip install .

Adjust the path for your MATLAB version and OS.

stdio vs SSE — which should I use?

  • stdio: Single user, simple setup. The AI agent launches the server process directly.
  • SSE: Multiple users, shared server. Users connect over HTTP. Requires more setup but supports concurrent access with session isolation.

Can I run the server remotely?

Yes, with SSE transport. Start the server on a remote machine and connect via HTTP. Always put it behind a reverse proxy with authentication for production use.

Usage

How does async execution work?

Code that finishes within sync_timeout (30s default) returns immediately. Longer code is automatically promoted to an async job — the agent gets a job_id and can poll for progress with get_job_status.

How do I report progress from long-running jobs?

Use the mcp_progress() helper in your MATLAB code:

mcp_progress(__mcp_job_id__, 50, 'Halfway done');

Can I use my own MATLAB functions?

Yes, two ways:

  1. Custom tools (recommended): Define them in custom_tools.yaml and they become first-class MCP tools with parameter validation and help text.
  2. Path configuration: Add your function directories to workspace.default_paths in config, then call them via execute_code.

Are MATLAB plots interactive?

Yes! MATLAB figures are automatically converted to Plotly JSON, which renders as interactive charts in web-based clients. A static PNG and thumbnail are also generated as fallbacks. The conversion preserves line styles, colors, markers, legends, axis labels, and supports subplots and multiple axes.

What plot types are supported for Plotly conversion?

Line, scatter, bar, area, subplots (subplot/tiledlayout), multiple axes, and log/linear scales. Complex custom graphics may fall back to static PNG.

Can I read files back from the session?

Yes, three tools are available:

  • read_script — read .m script files as text
  • read_data — read data files (.mat, .csv, .json, .txt, .xlsx) with summary or raw mode
  • read_image — read image files (.png, .jpg, .gif) as inline images that render in agent UIs

Use list_files first to see what files are available in your session.

Can I upload data files?

Yes, use upload_data to upload files to the session directory. Then read them back with read_data, read_image, or read_script.

Monitoring & Diagnostics

How do I check server health?

Use get_server_health to get a health status (healthy/degraded/unhealthy) with issue detection.

What metrics are available?

Use get_server_metrics for comprehensive metrics: engine pool stats, active jobs and sessions, system memory, and uptime.

How do I see recent errors?

Use get_error_log to retrieve recent errors and notable events.

Performance

How many engines should I run?

  • Personal use: 1-2 engines
  • Small team (2-5 users): 2-4 engines
  • Larger team: Scale based on concurrent usage, up to your MATLAB license limit

On macOS, MATLAB limits you to ~4 concurrent engines.

Will it slow down my MATLAB?

Each engine is an independent MATLAB process. Running multiple engines uses memory proportional to the number of engines (typically 500MB-2GB per engine depending on loaded toolboxes).

What happens when all engines are busy?

Requests queue up (configurable queue_max_size, default 50). If the pool hasn't reached max_engines, a new engine is started proactively. Requests are served FIFO as engines become available.

Troubleshooting

The server won't start — "MATLAB Engine not found"

Ensure the MATLAB Engine API for Python is installed:

cd /path/to/MATLAB/extern/engines/python
pip install .

Verify with:

python -c "import matlab.engine; print(matlab.engine.__version__)"

Jobs are stuck in pending state

Check get_pool_status to see if engines are available. If all engines are busy or unhealthy, use get_error_log to diagnose issues. Restart the server if needed.

Plots aren't converting to Plotly

Complex custom graphics may not convert. Check the static PNG (*.png) and thumbnail (*_thumbnail.png) generated in the results directory. File reading tools will always return the PNG as a fallback.

Memory usage is growing

Each engine holds a workspace in memory. With SSE, workspaces are cleared between sessions if workspace_isolation: true (default). For stdio, the workspace persists for the session lifetime. Restart the server to free all memory.

Docker container exits immediately

Check logs: docker logs <container_id>. Common issues:

  • MATLAB path not mounted correctly. Verify with docker exec <container_id> ls -la /opt/matlab
  • MATLAB Engine API not installed in the image. Rebuild the image.

Security

Is it safe to expose over the network?

For SSE transport:

  • Always put it behind an authenticating reverse proxy
  • Set require_proxy_auth: true in config
  • Bind to 127.0.0.1 if the proxy is on the same machine

Can agents run arbitrary system commands?

No. The security validator blocks system(), unix(), dos(), !, eval(), feval(), evalc(), evalin(), assignin(), perl(), and python() by default. You can customize the blocklist in security.blocked_functions.

Are user sessions isolated?

Yes. When workspace_isolation: true (default), the workspace is fully cleared between sessions: clear all; clear global; clear functions; fclose all; restoredefaultpath. Each user gets their own isolated session with independent file directories.

Is there authentication for the server?

SSE transport supports:

  • Proxy authentication: Set require_proxy_auth: true and put the server behind an authenticating reverse proxy
  • Custom auth: Implement your own authentication layer in front of the SSE endpoint

For stdio, authentication is handled by the client (Claude Desktop, Cursor, etc.).

Development

How do I run tests?

pip install -e ".[dev]"
pytest tests/ -v

Tests use a mock MATLAB engine — no MATLAB installation needed for testing.

How do I add a new MCP tool?

  1. Create the implementation in src/matlab_mcp/tools/
  2. Register it in server.py with @mcp.tool
  3. Add tests in tests/

Can I contribute?

Yes! Open an issue or PR on GitHub. Check the README and wiki for contribution guidelines.

Clone this wiki locally