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 the Installation section in the README.

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

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:

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 up (edit docker-compose.yml to set your MATLAB path).

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. Use this for personal or Cursor/Claude Desktop integration.
  • SSE: Multiple users, shared server. Users connect over HTTP with session isolation. Requires more setup but supports concurrent access and multiple agents. Use this for team environments.

Start with:

matlab-mcp                           # stdio (default)
matlab-mcp --transport sse           # SSE (multi-user)

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 an authenticating reverse proxy for production use. Configure require_proxy_auth: true in config.yaml and bind to 127.0.0.1 if the proxy is on the same machine.

How do I configure the server?

All settings are in config.yaml with sensible defaults. Override any setting via environment variables:

export MATLAB_MCP_POOL_MIN_ENGINES=4
export MATLAB_MCP_POOL_MAX_ENGINES=16
export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60
export MATLAB_MCP_SERVER_TRANSPORT=sse

Key sections: server (transport, host, port, logging), pool (engine scaling), execution (timeouts, workspace isolation), security (code blocklist), and workspace (default paths).

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 using get_job_status. Retrieve full results with get_job_result when done.

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');

Progress updates are tracked and returned via get_job_status.

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. See the README for examples.
  2. Path configuration: Add your function directories to workspace.default_paths in config.yaml, then call them via execute_code.

Are MATLAB plots interactive?

Yes! MATLAB figures are automatically converted to interactive Plotly JSON, which renders as interactive charts in web-based clients. A static PNG and thumbnail are also generated as fallback for non-interactive clients.

What plot types are supported for Plotly conversion?

  • Supported: Line, scatter, bar, area, histogram, surface, image plots
  • Advanced: Subplots (subplot and tiledlayout), multiple axes, log/linear scales, colormaps
  • Style fidelity: Line styles (-- → dash, -. → dot), marker shapes (o → circle), colors (RGB), line widths, font sizes, axis labels, titles, legends, grid lines, and background colors

Complex custom graphics or 3D plots 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 format
  • 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 files to the session?

Yes, use upload_data to upload files (base64 encoded). Delete files with delete_file.

How do I check my code before running it?

Use check_code to run MATLAB's built-in checkcode/mlint. It returns structured warnings and errors without executing anything.

Performance

How many engines should I run?

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

The pool automatically scales between min_engines and max_engines based on demand. 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). System performance depends on your hardware.

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 (threshold configurable via proactive_warmup_threshold). Requests are served FIFO as engines become available.

How do I monitor pool and server health?

Use these tools:

  • get_pool_status — Engine pool stats (available, busy, max)
  • get_server_metrics — Comprehensive metrics (pool, jobs, sessions, system resources)
  • get_server_health — Health status with issue detection (healthy/degraded/unhealthy)
  • get_error_log — Recent errors and notable events

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.yaml
  • 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 dangerous functions by default:

  • system(), unix(), dos(), ! — shell execution
  • eval(), feval(), evalc(), evalin() — dynamic code execution
  • assignin() — workspace manipulation
  • perl(), python() — external process execution

You can customize the blocklist in security.blocked_functions in config.yaml. Code is checked before execution via check_code.

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 SSE client gets its own isolated workspace.

What if I need to allow a blocked function?

You can customize security.blocked_functions in config.yaml to remove functions from the blocklist, but this is not recommended for untrusted agents. Use custom tools instead to safely expose your MATLAB code.

Troubleshooting

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

Cause: MATLAB Engine API not installed or not on the Python path.

Fix:

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

Verify with: python -c "import matlab.engine; print('OK')"

"Engine start timeout" or engines fail to start

Cause: MATLAB installation path not found, licensing issue, or insufficient system resources.

Fix:

  1. Verify MATLAB is installed: which matlab or check C:\Program Files\MATLAB
  2. Set explicit path: export MATLAB_MCP_POOL_MATLAB_ROOT=/path/to/MATLAB
  3. Check MATLAB license: matlab -r "license('test'); quit"
  4. Increase timeout: export MATLAB_MCP_POOL_ENGINE_START_TIMEOUT=180
  5. Check logs: tail -f logs/server.log

Code execution fails silently or with cryptic errors

Cause: Code contains syntax errors, undefined variables, or blocked functions.

Fix:

  1. Use check_code first to validate syntax
  2. Run simpler code to isolate the issue
  3. Check logs for full error messages: log_level: "debug" in config.yaml
  4. Ensure required toolboxes are installed: use list_toolboxes

"Job not found" or results missing

Cause: Job ID expired or wrong session.

Fix:

  1. Use list_jobs to see all active jobs
  2. Check job status with get_job_status before results are ready
  3. Retrieve results with get_job_result (not from MATLAB directly)

Plots aren't converting to Plotly or show as PNG

Cause: Unsupported plot type, corrupted figure, or extraction failed.

Fix:

  1. Use supported plot types: line, scatter, bar, histogram, surface, image
  2. Check for custom graphics objects or nested figures
  3. Add explicit axis labels and titles for better conversion
  4. PNG fallback always works — plots are never lost

Docker container exits or can't find MATLAB

Cause: MATLAB path not mounted correctly or environment variable not set.

Fix:

docker run -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab \
  -v /Applications/MATLAB_R2024a.app:/opt/matlab:ro \
  matlab-mcp

Verify with: docker exec <container> ls /opt/matlab

SSE server slow or clients disconnect

Cause: Network latency, proxy timeouts, or high server load.

Fix:

  1. Check get_server_health for degraded status
  2. Scale engines: max_engines > current demand
  3. Increase drain timeout: server.drain_timeout_seconds: 600
  4. Monitor reverse proxy logs for dropped connections

"Workspace isolation failed" or clear all errors

Cause: Corrupted engine state or locked files/processes.

Fix:

  1. Disable isolation temporarily to diagnose: workspace_isolation: false (dev only)
  2. Restart the engine pool: scale to 0 then back up
  3. Check for open file handles: fopen('all') in your code

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 the @mcp.tool decorator
  3. Add tests in tests/
  4. Update the README MCP Tools Reference table

Can I contribute?

Yes! Open an issue or PR on GitHub. Check the README for development setup and the wiki for design docs.

Clone this wiki locally