Skip to content

FAQ

Jump to bottom
github-actions[bot] edited this page Apr 3, 2026 · 20 revisions

FAQ — MATLAB MCP Server

General / Overview

What is the MATLAB MCP Server?

The MATLAB MCP Server is a Python-based Model Context Protocol (MCP) server that bridges AI coding agents (Claude, Cursor, Copilot) to MATLAB. It lets agents execute MATLAB code, discover toolboxes, check code quality, view interactive plots, and manage files — all through the MCP protocol. See the README for a full overview.

Which versions are supported?

  • MATLAB: R2022b and later with the Engine API for Python installed
  • Python: 3.10, 3.11, 3.12
  • Platforms: Windows 10/11, macOS 11+, Linux (Ubuntu 20.04+)

What is the license?

This project is licensed under the MIT License. See LICENSE for details.

Setup

How do I install the MATLAB Engine API?

# Navigate to your MATLAB installation's Python engine directory
cd /Applications/MATLAB_R2024a.app/extern/engines/python  # macOS
# cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"  # Windows

# Install into your Python environment
pip install .

On Windows, the install.bat one-click installer handles this automatically.

Should I use stdio or SSE transport?

Transport Use Case Setup
stdio Single user, development, local testing Simplest — agent launches server directly
streamablehttp Multiple users, remote agents, Codex CLI Requires reverse proxy for production; recommended for new deployments
SSE Multiple users, backward compat (deprecated) Works but being phased out in favor of streamablehttp

Recommendation: Use streamablehttp for new setups. It's the modern standard and required for Codex CLI support.

How do I set up the server on Windows without admin rights?

Use the one-click installer:

git clone https://github.com/HanSur94/matlab-mcp-server-python.git
cd matlab-mcp-server-python
install.bat

The installer creates a virtual environment, installs everything from bundled wheels (fully offline), and auto-detects your MATLAB installation. No admin rights needed. See docs/windows-deployment.md for details.

Can I run the server in Docker?

Yes. The project includes Dockerfile and docker-compose.yml. The Docker image does not include MATLAB — you must mount your local MATLAB installation as a volume:

docker-compose up

See Installation for Docker configuration examples.

How do I generate an auth token?

Run the server with the --generate-token flag to print a random 64-character hex token:

matlab-mcp --generate-token

# Output:
# Bearer token (64 hex chars):
# 3f7a9c2b1e8d5f4a6c9b2e1a7d3f9c5b8a2d4e6f7c9a1b3e5f7d9a2c4b6e8
#
# Export on POSIX (bash/zsh/fish):
#   export MATLAB_MCP_AUTH_TOKEN=3f7a9c2b1e8d5f4a6c9b2e1a7d3f9c5b8a2d4e6f7c9a1b3e5f7d9a2c4b6e8
#
# Export on Windows (cmd.exe):
#   set MATLAB_MCP_AUTH_TOKEN=3f7a9c2b1e8d5f4a6c9b2e1a7d3f9c5b8a2d4e6f7c9a1b3e5f7d9a2c4b6e8
#
# Export on Windows (PowerShell):
#   $env:MATLAB_MCP_AUTH_TOKEN='3f7a9c2b1e8d5f4a6c9b2e1a7d3f9c5b8a2d4e6f7c9a1b3e5f7d9a2c4b6e8'

Then set the environment variable and start the server:

export MATLAB_MCP_AUTH_TOKEN=3f7a9c2b1e...
matlab-mcp --transport streamablehttp

Performance

How many MATLAB engines should I run?

User Count Recommended Pool
Personal (1 user) 1–2 engines
Small team (2–5 users) 2–4 engines
Larger team (5+ users) Scale to license limit; typically 4–8

Configure via config.yaml:

pool:
  min_engines: 2      # Start with 2
  max_engines: 10     # Scale up to 10 if needed

Or via environment variable:

export MATLAB_MCP_POOL_MIN_ENGINES=2
export MATLAB_MCP_POOL_MAX_ENGINES=10

What are typical resource requirements per engine?

  • Memory: 500MB–2GB per engine (varies by loaded toolboxes)
  • CPU: Minimal idle; full core usage during execution
  • Startup time: 10–30 seconds per new engine (first startup is slower)

What happens when all engines are busy?

  • New requests queue up (default queue_max_size: 50)
  • If the pool hasn't reached max_engines, a new engine starts automatically
  • Requests are served FIFO as engines become available
  • If queue is full, requests receive an error

Adjust via config:

pool:
  max_engines: 15          # Higher limit for scaling
  queue_max_size: 100      # Larger queue

How do I optimize for long-running jobs?

Long jobs (>30s) are auto-promoted to async execution. Tune these settings:

execution:
  sync_timeout: 30           # Threshold for auto-async promotion
  max_execution_time: 86400  # Max job runtime (24 hours)
  job_retention_seconds: 86400  # Keep results for 24 hours

Agents can poll job status with get_job_status while it's running. For progress updates, use mcp_progress() in your MATLAB code. See Async Jobs for details.

Integration

How do I connect Claude Desktop?

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp"
    }
  }
}

Then restart Claude Desktop. See Installation for full setup.

How do I connect Claude Code?

claude mcp add matlab

For custom settings (e.g., different transport), use:

claude mcp set matlab --command "matlab-mcp --transport streamablehttp"

How do I connect Cursor?

Add to .cursor/rules or your Cursor config:

{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp",
      "args": ["--transport", "streamablehttp"]
    }
  }
}

How do I connect Codex CLI?

Codex CLI requires streamable HTTP transport. See docs/agent-onboarding.md for the exact connection config with bearer token authentication.

Can I use the server with a CI/CD pipeline?

Yes. The server supports stdio mode (default) which is CI-friendly:

# In your CI step
export MATLAB_MCP_POOL_MIN_ENGINES=1
export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=120
matlab-mcp --transport stdio

Or containerize it:

docker build -t matlab-mcp .
docker run -e MATLAB_MCP_AUTH_TOKEN=... matlab-mcp

How do I monitor the server in production?

The server exposes three monitoring tools via MCP:

  • get_server_health — health status, uptime, issues
  • get_server_metrics — pool utilization, job counts, error rates, system stats
  • get_error_log — recent error events with 24-hour error rate

Plus HTTP endpoints for dashboard:

  • /health — JSON health status
  • /metrics — JSON metrics snapshot
  • /dashboard — Web UI (if monitoring enabled)

Configure via:

monitoring:
  enabled: true                    # Enable metrics collection
  sqlite_db_path: ./monitoring.db  # Metrics database
  dashboard_enabled: true          # Enable web dashboard
  dashboard_port: 8766             # Dashboard port

Troubleshooting & FAQs by Topic

MATLAB Engine Issues

Q: "MATLAB Engine startup failed"

  • Verify MATLAB is installed: matlab -version
  • Verify Engine API is installed: python -c "import matlab.engine; print(matlab.engine.start_matlab)"
  • Check that MATLAB_ROOT env var is set if MATLAB is in a non-standard location

See Troubleshooting for more.

Q: "macOS MATLAB Engine limit exceeded"

On macOS, MATLAB limits you to ~4 concurrent engines. Either:

  • Reduce pool.max_engines to 4
  • Switch to a Linux/Windows machine with higher limits

Q: "MATLAB hangs on startup"

On Windows with network drives, MATLAB can hang during startup. Workaround:

  • Map network drives as persistent before starting MATLAB
  • Or use a local drive for the workspace

Code Execution

Q: "Blocked function error"

The security validator blocks dangerous functions (system, eval, etc.) by default. Either:

  1. Rewrite your code to avoid the blocked function
  2. Disable the block for that specific function in config.yaml:
security:
  blocked_functions:
    - system
    - eval
    # Remove the function you need here

Q: "Code is timing out"

Code exceeding sync_timeout (default 30s) auto-promotes to async. Either:

  • Increase execution.sync_timeout in config
  • Let it run async and poll with get_job_status
  • Optimize the MATLAB code

File Operations

Q: "Upload failed — file too large"

Default limit is 100MB. Increase via:

security:
  max_upload_size_mb: 500

Q: "Path traversal error"

Filenames are sanitized to prevent path traversal. Use simple filenames without ../, /, or absolute paths.

Plotting

Q: "Plotly conversion failed"

Some complex custom plots may not convert. The server falls back to a static PNG. This is expected behavior.

Q: "Plot doesn't show colors/styles"

The conversion supports common plot types (line, scatter, bar, surface). Custom properties may be lost. Check the static PNG fallback.

Security

Is it safe to expose over the network?

For HTTP/SSE transports:

  • Always put behind an authenticating reverse proxy (nginx, Apache)
  • Set require_proxy_auth: true in config
  • Bind to 127.0.0.1 if the proxy is local
  • Use bearer tokens via environment variables only — never in config files

Can agents run arbitrary system commands?

No. The security validator blocks 11 dangerous functions by default:

  • system, unix, dos, ! (shell escapes)
  • eval, evalc, evalin (code execution)
  • feval (function indirection)
  • assignin (workspace manipulation)
  • perl, python (shell bridges)

You can customize the blocklist in config.yaml. See Security for details.

Are user sessions isolated?

Yes. Each session gets:

  • Isolated workspace — clear all; clear global; clear functions between sessions
  • Private temp directory — files can't leak between sessions
  • Session timeout — idle sessions are cleaned up after session_timeout (default 1 hour)

Architecture & Design

For detailed architecture, data flows, and design decisions, see the Wiki:

graph TD
    Agent["AI Agent<br/>(Claude, Cursor, etc)"]
    MCP["MCP Protocol<br/>(stdio/HTTP)"]
    FastMCP["FastMCP 3.x<br/>Server"]
    Auth["Bearer Token<br/>Middleware"]
    SessionMgr["Session Manager<br/>(per-user workspaces)"]
    Pool["Engine Pool<br/>(elastic scaling)"]
    Engines["MATLAB Engines<br/>(R2022b+)"]
    
    Agent -->|"MCP Messages"| MCP
    MCP --> Auth
    Auth --> FastMCP
    FastMCP --> SessionMgr
    FastMCP --> Pool
    Pool --> Engines
    SessionMgr --> Engines
Loading

Key components:

  • FastMCP: MCP server framework (v3.x)
  • SessionManager: Per-user workspace isolation and temp directories
  • EnginePoolManager: Elastic MATLAB engine scaling (min → max engines)
  • JobExecutor: Sync/async job orchestration with auto-promotion
  • SecurityValidator: Blocklist-based code safety checks
  • Monitoring: Real-time metrics, health, and error logs

Development & Contribution

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 implementation in src/matlab_mcp/tools/
  2. Register with @mcp.tool in server.py
  3. Add tests in tests/test_tools_*.py

How do I contribute?

  1. Fork the repo
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Write tests and code
  4. Run tests: pytest tests/ -v
  5. Run linter: ruff check . && ruff format .
  6. Open a PR

See CONTRIBUTING for guidelines.

For more help:

Clone this wiki locally