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

docker compose up

Setup

How do I install the MATLAB Engine API?

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

On Windows:

cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"
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. Best for personal use.
  • SSE: Multiple users, shared server. Users connect over HTTP with session isolation. Requires reverse proxy authentication for production.
# Single user (stdio)
matlab-mcp

# Multi-user (SSE)
matlab-mcp --transport sse

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 your config and bind to 127.0.0.1 if the proxy is on the same machine.

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. See the Async Job Management tools.

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

This requires the __mcp_job_id__ variable, which is automatically available in async job contexts.

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. 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 and thumbnail are also generated as fallbacks. The conversion extracts axes, line data, labels, colors, markers, legends, and subplots.

What plot types are supported for Plotly conversion?

Supported: Line, scatter, bar, area, subplots (subplot/tiledlayout), multiple axes, log/linear scales, and image plots.

Style preservation: Line styles (-- → dash), marker shapes (o → circle), colors (RGB), line widths, font sizes, axis labels, titles, legends, grid lines, axis limits, and background colors are all preserved.

Complex custom graphics may fall back to static PNG if the conversion cannot map the plot structure to Plotly.

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 the session?

Use the upload_data tool with base64-encoded content:

tool: upload_data
filename: my_data.csv
content_base64: <base64-encoded file content>

Files are stored in the session directory and can be referenced in MATLAB code.

Performance

How many engines should I run?

Configure via pool.min_engines and pool.max_engines:

  • Personal use: min: 1, max: 4 (stdio transport)
  • Small team (2-5 users): min: 2, max: 8 (SSE transport)
  • Larger team: Scale based on concurrent usage, up to your MATLAB license limit

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

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). The pool automatically scales down idle engines after scale_down_idle_timeout (default 15 minutes).

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 (default 80%). Requests are served FIFO as engines become available.

How do I monitor engine pool performance?

Use the get_pool_status tool to check:

  • Number of available, busy, and total engines
  • Queue size
  • Health status

For detailed metrics, use get_server_metrics which provides pool stats, job stats, session count, and system information. Use get_server_health to detect issues (healthy/degraded/unhealthy).

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
  • Configure trusted_proxy_headers to validate X-Forwarded-For or X-Original-User headers

For stdio transport, the server only communicates with a single client and is not exposed to the network.

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.security.blocked_functions. Custom tools are pre-validated when defined in custom_tools.yaml.

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 a separate session directory with isolated files. SSE transport requires authentication to maintain session boundaries.

How do I enable code checking before execution?

Code checking is available via the check_code tool, which runs MATLAB's checkcode/mlint before execution. Set execution.security.require_code_check: true in config to enforce this globally.

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 documentation

How do I create custom tools?

Define them in custom_tools.yaml with MATLAB function references:

tools:
  - name: my_tool
    matlab_function: mylib.my_function
    description: "Description for the agent"
    parameters:
      - name: param1
        type: string
        required: true
    returns: "Description of return value"

Custom tools are automatically validated and exposed as MCP tools.

Can I contribute?

Yes! Open an issue or PR on GitHub. Please include tests and documentation updates.

Troubleshooting

MATLAB Engine API not found

Install it from your MATLAB installation:

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

Verify installation:

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

Server won't start

Check the log file (default ./logs/server.log). Common issues:

  • MATLAB Engine API not installed
  • Port already in use (change server.port in config)
  • MATLAB installation not found (set pool.matlab_root explicitly)

Async job stuck or timing out

Check job status with get_job_status. If a job is stuck:

  • Cancel it with cancel_job
  • Check execution.async_timeout in config (default 3600 seconds)
  • Review MATLAB code for infinite loops or missing mcp_progress() calls

Plots not converting to Plotly

Complex custom graphics may not convert. Fallback to static PNG is automatic. For better conversion:

  • Use standard MATLAB plot functions (plot, scatter, bar, etc.)
  • Avoid custom graphics objects
  • Simplify figure complexity if possible

Out of memory errors

Reduce pool.max_engines or the number of concurrent users. Each engine uses 500MB-2GB. Monitor system resources with get_server_metrics.

MATLAB license errors in multi-user setup

Ensure your MATLAB license supports concurrent engines. Use pool.max_engines to stay within license limits. Check MATLAB documentation for concurrent license requirements.

Clone this wiki locally