Skip to content

FAQ

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

FAQ

General

What MATLAB versions are supported?

MATLAB 2020b 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 Installation.

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 Installation for Docker setup instructions.

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. See Installation for details.

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.

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. See Async Jobs.

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. See Custom Tools.
  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.

What plot types are supported for Plotly conversion?

Line, scatter, bar, area, histogram, surface, image plots, and subplots (subplot/tiledlayout). Complex custom graphics may fall back to static PNG. Supported styles include line styles (--, -.), marker shapes, colors (RGB), line widths, font sizes, axis labels, titles, legends, grid lines, axis limits, and background colors.

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.

How do I upload files to MATLAB?

Use the upload_data tool:

upload_data(filename="data.csv", content_base64="base64_encoded_content")

The file will be available in your MATLAB session directory.

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

Configure min_engines and max_engines in config.yaml. 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 when utilization exceeds proactive_warmup_threshold. Requests are served FIFO as engines become available.

How can I monitor server performance?

Use the get_server_metrics and get_server_health tools to check:

  • Engine pool stats (available/busy/max)
  • Job queue depth
  • Session count
  • System resource usage
  • Error rates and recent issues

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
  • Use HTTPS in production

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 execution.blocked_functions. See Security.

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.

What security checks are performed?

  • Code validator: Blocks dangerous functions before execution
  • Proxy auth: Requires reverse proxy authentication for SSE deployments
  • Session isolation: Per-user workspaces with auto-cleanup
  • Health monitoring: Detects and reports security-relevant errors

Troubleshooting

MATLAB Engine API won't install

Ensure you're using the correct path for your MATLAB version and OS:

# macOS
cd /Applications/MATLAB_R2024a.app/extern/engines/python
pip install .

# Windows
cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"
pip install .

If the path doesn't exist, check your MATLAB installation directory.

"No MATLAB engines available"

Check engine pool status with get_pool_status. If all engines are busy, wait for one to free up or increase max_engines in config. Check the error log with get_error_log for engine startup failures.

Code execution times out

Increase sync_timeout in config.yaml (default 30s). Code exceeding this timeout automatically becomes an async job. For very long operations, monitor progress with get_job_status.

Plots not converting to Plotly

Complex custom graphics may not convert. Check that your plot uses standard MATLAB plot functions (line, scatter, bar, surface, etc.). Use read_image to retrieve the static PNG fallback.

Docker container won't start

Verify:

  • MATLAB is mounted at the correct path
  • MATLAB_MCP_POOL_MATLAB_ROOT matches the mount point
  • The mounted MATLAB installation is valid
  • Check Docker logs: docker logs <container_id>

Server crashes or becomes unresponsive

Check the error log: get_error_log. Common causes:

  • Engine pool exhaustion — increase max_engines
  • Out of memory — reduce engine count or add system RAM
  • Corrupted MATLAB workspace — set workspace_isolation: true

Restart the server and review logs/server.log.

High memory usage

Each MATLAB engine uses 500MB-2GB depending on loaded toolboxes. Reduce max_engines or set scale_down_idle_timeout to reclaim memory from idle engines. Monitor with get_server_metrics.

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.

Clone this wiki locally