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:
```bash
pip install matlab-mcp-python

You still need to install the MATLAB Engine API separately from your MATLAB installation. See the Quick Start section in the README.

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 after editing the compose file 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.
  • SSE: Multiple users, shared server. Users connect over HTTP with session isolation. Requires more setup but supports concurrent access and persistent workspaces.

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. Set require_proxy_auth: true in config.

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 and retrieve results with get_job_result.

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 when the agent checks 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 full parameter validation and help text. See the Custom Tools example in the README.
  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 is also generated as a fallback, and a thumbnail for quick preview.

What plot types are supported for Plotly conversion?

Line, scatter, bar, histogram, surface, and image plots. Complex custom graphics may fall back to static PNG. Configure conversion behavior in the output section of config.yaml.

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. The session directory is configurable via execution.temp_dir.

Can I upload files to the session?

Yes, use the upload_data tool:

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

Max upload size is configurable (security.max_upload_size_mb, default 100MB). Cleanup on disconnect is controlled by execution.temp_cleanup_on_disconnect.

What monitoring tools are available?

Three MCP tools provide real-time visibility:

  • get_pool_status — engine pool stats (available/busy/max engines)
  • get_server_metrics — comprehensive metrics (pool, jobs, sessions, system resource usage)
  • get_server_health — health status with issue detection (healthy/degraded/unhealthy)

Additionally, a web dashboard is available at http://localhost:8766/dashboard (stdio) or http://localhost:8765/dashboard (SSE).

Performance

How many engines should I run?

  • Personal use: 1-2 engines (set pool.min_engines: 1, pool.max_engines: 2)
  • 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. Configure via pool.min_engines and pool.max_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). Monitor via get_server_metrics.

What happens when all engines are busy?

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

How does the engine pool scale?

The pool maintains pool.min_engines warm engines. When load exceeds proactive_warmup_threshold (default 0.8), new engines are started up to pool.max_engines. Idle engines scale down after pool.scale_down_idle_timeout (default 900 seconds).

Can I pin a session to a single engine?

Yes, set execution.engine_affinity: true in config. This ensures all code from a session runs on the same engine, useful for state-dependent workflows.

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, or use firewall rules

The server does not implement authentication — rely on your reverse proxy (nginx, Apache, etc.).

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. Set security.blocked_functions_enabled: false to disable all checks (not recommended for untrusted input).

Are user sessions isolated?

Yes. When execution.workspace_isolation: true (default), each session gets a fresh workspace. On disconnect, if execution.temp_cleanup_on_disconnect: true, temporary files are deleted. Workspaces are fully cleared: clear all; clear global; clear functions; fclose all; restoredefaultpath.

Can I restrict which toolboxes are available?

Yes. Use toolboxes.mode to control exposure:

  • whitelist (default) — only listed toolboxes are discoverable
  • blacklist — all toolboxes except listed ones are discoverable
  • all — all toolboxes are discoverable

Configure the list in toolboxes.list.

How is upload security handled?

Upload size is capped by security.max_upload_size_mb (default 100MB). Uploaded files are stored in execution.temp_dir and cleaned up on disconnect if execution.temp_cleanup_on_disconnect: true. Filenames are sanitized.

Configuration

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

# Override pool size
export MATLAB_MCP_POOL_MIN_ENGINES=4
export MATLAB_MCP_POOL_MAX_ENGINES=16

# Override sync timeout (promote to async after 60s instead of 30s)
export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60

# Override transport
export MATLAB_MCP_SERVER_TRANSPORT=sse

All environment variables are prefixed with MATLAB_MCP_ and use uppercase with underscores. Refer to config.yaml for the full list.

Troubleshooting

MATLAB Engine API not found

Ensure it's installed from your MATLAB installation:

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

Verify with:

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

"No module named 'matlab_mcp'"

Reinstall the package:

pip install -e ".[dev]"  # from source
# or
pip install matlab-mcp-python  # from PyPI

Engines won't start

Check log_file (default ./logs/server.log) for detailed errors. Common issues:

  • MATLAB root path is incorrect — set MATLAB_MCP_POOL_MATLAB_ROOT=/path/to/matlab
  • License server unreachable — verify network connectivity
  • Insufficient memory — reduce pool.max_engines

High memory usage

Each engine uses 500MB-2GB depending on toolboxes. Monitor with get_server_metrics. Reduce pool.max_engines or set pool.scale_down_idle_timeout lower to scale down unused engines faster.

Jobs stuck in "pending" state

Check get_server_metrics for pool status. If all engines are busy, requests queue. Increase pool.max_engines if this is persistent. For truly stuck jobs, use cancel_job to free the engine.

Code execution times out

Default execution.sync_timeout is 30s. Code longer than this auto-promotes to async. To increase the threshold:

export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60

Hard limit is execution.max_execution_time (default 24h).

Plot conversion fails (returns static PNG only)

This is expected for complex custom graphics. Ensure output.plotly_conversion: true is set in config. Most standard plots (line, scatter, bar, histogram, surface, image) convert automatically.

Docker container exits immediately

Check logs:

docker logs <container_id>

Ensure MATLAB path is mounted correctly:

docker run -v /path/to/MATLAB:/opt/matlab:ro -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab matlab-mcp

SSE transport connection refused

Verify the server is bound to the correct host and port. Default is 0.0.0.0:8765. Check firewall rules and that no other service is using the port.

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

Can I contribute?

Yes! Open an issue or PR on GitHub.

How do I debug issues?

Set server.log_level: "debug" in config and check the log file for detailed output. For remote debugging, increase verbosity:

export MATLAB_MCP_SERVER_LOG_LEVEL=debug
matlab-mcp

The error log is also accessible via the get_error_log MCP tool (limit configurable).

Clone this wiki locally