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 README for installation 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:

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

See the README for complete Docker setup instructions.

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. See the README for details.

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.

Is there a one-click Windows installer?

Yes. Windows users can run install.bat for a fully offline installation with no admin rights needed. It auto-detects MATLAB, creates a virtual environment, and installs from bundled wheels. Works on Windows 10/11 with Python 3.10, 3.11, or 3.12.

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 README for async job examples.

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 is reported as a percentage and can be polled 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 Plotly JSON, which renders as interactive charts in web-based clients. The server also generates a static PNG and thumbnail as fallback. Line styles, colors, markers, legends, and axis labels are all preserved in the conversion.

What plot types are supported for Plotly conversion?

Line, scatter, bar, area, subplots (subplot/tiledlayout), multiple axes, and image plots. Log/linear axis scales are supported. 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 format
  • read_image — read image files (.png, .jpg, .gif) — render inline 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 file content:

upload_data(filename: "mydata.csv", content_base64: "...")

Uploaded files are placed in the session working directory and can be read with read_data or read_script.

Performance

How many engines should I run?

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

On macOS, MATLAB limits you to ~4 concurrent engines. Adjust 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 only started when needed (min_engines baseline, up to max_engines on demand).

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 engine pool status?

Use the get_pool_status tool to check available/busy/max engines, or get_server_metrics for comprehensive metrics including job counts, session counts, and system resource usage.

Can I set a timeout for code execution?

Yes. Configure execution.sync_timeout (default 30s) in config.yaml — code running longer is automatically promoted to async. Long-running async jobs can report progress and be monitored via job status tools.

Troubleshooting

How do I check server health?

Use the get_server_health tool for health status (healthy/degraded/unhealthy) with issue detection. Use get_error_log to see recent errors and notable events.

What should I do if MATLAB Engine API installation fails?

Ensure you're running the pip install command from the correct MATLAB engine directory. The path varies by OS and MATLAB version:

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

If installation still fails, check that your MATLAB installation is complete and you have Python 3.10+ installed.

How do I see what's happening in the server?

Adjust log_level in config.yaml:

server:
  log_level: "debug"  # More verbose
  log_file: "./logs/server.log"

Or set the environment variable:

export MATLAB_MCP_SERVER_LOG_LEVEL=debug
matlab-mcp

How do I debug a custom tool?

  1. Test your MATLAB function directly in MATLAB to ensure it works
  2. Add it to custom_tools.yaml with proper parameter descriptions
  3. Use get_help to verify the tool is registered
  4. Call it with execute_code first to debug
  5. Check server logs (debug level) for detailed error messages

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 with proper certificates

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 via security.blocked_functions in config.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 has a separate session directory for uploaded files.

How do I customize security settings?

Edit config.yaml:

security:
  enabled: true
  blocked_functions:
    - "system"
    - "eval"
    - "feval"
    # Add custom blocked functions here

Or via environment variable:

export MATLAB_MCP_SECURITY_ENABLED=true

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

How do I add a custom tool via YAML?

  1. Create custom_tools.yaml in your config directory
  2. Define tools with name, MATLAB function, description, and parameters:
tools:
  - name: my_tool
    matlab_function: mylib.my_function
    description: "What it does"
    parameters:
      - name: param1
        type: string
        required: true
    returns: "Description of return value"
  1. Restart the server — tools are loaded on startup

Can I contribute?

Yes! Open an issue or PR on GitHub. The project welcomes bug reports, feature requests, and contributions.

What Python versions are supported?

Python 3.10, 3.11, and 3.12. The Windows installer includes all three versions; on macOS/Linux, ensure your Python version matches one of these.

Clone this wiki locally