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 Installation 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 (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.
  • SSE: Multiple users, shared server. Users connect over HTTP. Requires more setup but supports concurrent access and workspace 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.

How do I configure the server?

All settings live 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

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

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.
  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. The server extracts figure properties, maps MATLAB styles to Plotly, and returns both interactive JSON and a static PNG fallback.

What plot types are supported for Plotly conversion?

Line, scatter, bar, area, histogram, surface, image, and subplot plots. Features preserved include line styles (-- → dash), marker shapes (o → circle), colors (RGB), legends, axis labels, titles, log/linear scales, and subplots (subplot/tiledlayout). 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 files to the session?

Yes, use the upload_data tool to upload files to the session directory. You can then reference them in your MATLAB code.

How do I check code for errors before running it?

Use the check_code tool to run checkcode/mlint. It returns structured warnings and errors without executing the code.

Performance

How many engines should I run?

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

Configure pool.min_engines and pool.max_engines in config.yaml.

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). Engines are created on demand and reused across jobs.

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.

How do I monitor pool and job performance?

Use the monitoring tools:

  • get_pool_status — engine pool stats (available/busy/max)
  • get_server_metrics — comprehensive server metrics (pool, jobs, sessions, system)
  • 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
  • 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 config.yaml under execution.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 session directory and workspace state.

What happens if I set require_proxy_auth: false?

The server will run but log a warning on startup. This is only safe for localhost development. For any network exposure, always use require_proxy_auth: true with a reverse proxy.

Troubleshooting

MATLAB Engine API won't install

Make sure you're installing from the correct MATLAB installation path:

  • macOS: /Applications/MATLAB_R202Xa.app/extern/engines/python
  • Windows: C:\Program Files\MATLAB\R202Xa\extern\engines\python
  • Linux: /usr/local/MATLAB/R202Xa/extern/engines/python

Adjust 202Xa for your MATLAB version.

"No MATLAB installation found"

The server couldn't locate MATLAB. Set MATLAB_ROOT environment variable:

export MATLAB_ROOT=/Applications/MATLAB_R2024a.app  # macOS
# set MATLAB_ROOT=C:\Program Files\MATLAB\R2024a  # Windows
matlab-mcp

Engines are taking a long time to start

First engine startup can take 10-30 seconds. Subsequent engines start faster (~5-10s). If engines consistently fail to start, check:

  • MATLAB license availability
  • System memory
  • Log file for detailed errors: cat ./logs/server.log

"Queue full" errors

The job queue has reached queue_max_size (default 50). Either:

  • Increase queue_max_size in config.yaml
  • Wait for jobs to complete
  • Increase max_engines to process jobs faster

Code execution times out

The default sync_timeout is 30 seconds. For longer tasks, either:

  • Increase sync_timeout in config.yaml
  • Let the code run async automatically (no timeout penalty, agent gets job_id and can poll)

Docker container exits immediately

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

  • MATLAB path not mounted correctly (-v /path/to/MATLAB:/opt/matlab:ro)
  • Missing MATLAB_MCP_POOL_MATLAB_ROOT environment variable
  • MATLAB Engine API not installed in the mounted MATLAB

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 MCP Tools Reference section in README

Can I contribute?

Yes! Open an issue or PR on GitHub. Contributions are welcome for bug fixes, features, documentation, and test coverage.

How do I enable debug logging?

Set log_level: debug in config.yaml or:

export MATLAB_MCP_SERVER_LOG_LEVEL=debug
matlab-mcp

Debug logs include request/response details and engine lifecycle events.

Clone this wiki locally