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 guide for details.

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. Set MATLAB_MCP_POOL_MATLAB_ROOT environment variable to point to your mounted MATLAB installation.

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 session 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. Set require_proxy_auth: true in the security configuration.

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

Key sections: server (transport, host, port), pool (engine scaling), execution (timeouts, workspace isolation), and security (blocklists, authentication).

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 via get_job_status. See the Async Jobs documentation.

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

The agent can poll get_job_status to retrieve the current progress percentage and message.

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 Custom Tools documentation.
  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. Supported plot types include line, scatter, bar, area, histograms, surfaces, images, and subplots.

What plot types are supported for Plotly conversion?

Line, scatter, bar, area, histogram, surface, image, and subplots. Complex custom graphics may fall back to static PNG. Style fidelity includes line styles (-- → dash), marker shapes, colors (RGB), line widths, font sizes, axis labels, titles, legends, grid lines, 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 the session?

Use upload_data with base64-encoded content:

filename: "data.csv"
content_base64: "Y3VzdG9tZXIsYW1vdW50Cm..."

Can I check my code before running it?

Yes, use check_code to run MATLAB's checkcode/mlint validator. It returns structured warnings and errors without executing the code.

How do I see what's in my workspace?

Use get_workspace to list all variables, their types, and values. This is helpful for debugging and understanding session state.

Performance

How many engines should I run?

  • Personal use: 1-2 engines (configured via min_engines, max_engines)
  • 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. The pool automatically scales between min_engines and max_engines based on demand (queue_max_size: 50 by default).

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

What is engine affinity?

When engine_affinity: true, a session is pinned to a single engine. This preserves workspace state but limits parallelism. Default is false to maximize throughput across multiple users.

How do I monitor engine health?

Use get_pool_status to see available/busy/max engines, and get_server_metrics for comprehensive stats (pool, jobs, sessions, system resources).

Troubleshooting

The server won't start

Check that:

  1. MATLAB Engine API is installed: python -c "import matlab.engine"
  2. MATLAB installation is detected: check logs for matlab_root path
  3. No port conflicts (default: 8765 for SSE)
  4. Log file is writable: default location is ./logs/server.log

Jobs timeout or hang

Check max_execution_time (default 24h). If a job exceeds this, it's cancelled. You can also manually cancel_job by job ID.

Plots aren't rendering as Plotly

Complex custom graphics may not convert. Check read_image to view the static PNG fallback. Supported types are line, scatter, bar, area, histogram, surface, image, and subplots.

Getting "Engine startup timeout" errors

Increase engine_start_timeout in config (default 120 seconds). Long MATLAB startup times (especially with many toolboxes) may exceed the default.

Workspace isolation not working

Verify workspace_isolation: true in config. When enabled, clear all; clear global; clear functions; fclose all; restoredefaultpath runs between sessions.

Too many engines spawning

Check proactive_warmup_threshold and queue_max_size. Reduce max_engines or increase scale_down_idle_timeout (default 900s / 15 min) to retain fewer idle engines.

How do I get diagnostic information?

  • get_server_health — health status with issue detection (healthy/degraded/unhealthy)
  • get_error_log — recent errors and notable events
  • get_server_metrics — comprehensive stats (pool, jobs, sessions, system)
  • Log files: check ./logs/server.log (configurable)

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 for all connections

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 the security.code_blocklist configuration.

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 isolated workspace when using SSE transport.

How does authentication work?

For SSE transport, set require_proxy_auth: true to require the X-Authenticated-User header on all requests. This header should be set by your reverse proxy after authentication.

Can I restrict which functions are available?

Yes, use security.code_blocklist to extend the default blocklist. You can also use custom_tools.yaml to explicitly define which MATLAB functions are exposed as AI tools, giving you fine-grained control.

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 name, MATLAB function reference, description, parameters, and return description. The server automatically validates parameters and exposes them as first-class MCP tools with help text.

Can I contribute?

Yes! Open an issue or PR on GitHub. All contributions welcome.

How do I enable debug logging?

Set log_level: "debug" in config or via environment variable:

export MATLAB_MCP_SERVER_LOG_LEVEL=debug

Clone this wiki locally