Skip to content

Troubleshooting

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

Troubleshooting

Common Issues by Category

Installation

MATLAB Engine API not found

Symptom: ModuleNotFoundError: No module named 'matlab' or matlab.engine not found

Likely Cause: MATLAB Engine for Python not installed or not on Python path.

Solution:

  1. Verify MATLAB installation:

    which matlab  # or 'where matlab' on Windows

    If not found, MATLAB R2022b+ must be installed first.

  2. Install Engine API for your MATLAB version:

    macOS/Linux:

    cd "$(matlab -batch "disp(matlabroot)" -nojvm -nodisplay | tail -1)/extern/engines/python"
pip install .

    Windows (from MATLAB root directory):

    cd %MATLAB_ROOT%\extern\engines\python
pip install .

    Or specify MATLAB_ROOT explicitly:

    export MATLAB_ROOT="/Applications/MATLAB_R2024a.app"  # macOS
cd "$MATLAB_ROOT/extern/engines/python"
pip install .

  3. Verify installation:

    python -c "import matlab.engine; print('✓ MATLAB Engine API installed')"

  4. Check MATLAB version: Engine API requires R2022b or later. If older:

    matlab -batch "version" -nojvm -nodisplay

    Upgrade MATLAB if version < R2022b.

Python version mismatch

Symptom: ImportError: DLL load failed (Windows) or compilation errors during pip install matlabengine

Likely Cause: Python version not compatible with installed MATLAB Engine API (Engine requires Python 3.10+).

Solution:

  1. Check Python version:

    python --version

    Requires Python 3.10+.

  2. If using wrong Python version, create a compatible virtual environment:

    python3.11 -m venv venv
source venv/bin/activate  # macOS/Linux
# or venv\Scripts\activate  # Windows

  3. Reinstall Engine API in virtual environment:

    pip install --upgrade matlabengine

Permission denied on Windows (no admin rights)

Symptom: PermissionError or Access denied during installation

Likely Cause: Attempting to install globally without admin rights.

Solution:

  1. Install to user directory:

    pip install --user matlabengine

  2. Or use virtual environment (preferred):

    python -m venv venv
venv\Scripts\activate
pip install matlabengine

  3. Install matlab-mcp:

    pip install --user matlab-mcp
# or from virtual environment: pip install matlab-mcp

Runtime

Server won't start

Symptom: matlab-mcp command not found or exits immediately

Likely Cause: Package not installed in active Python environment, or entry point misconfigured.

Solution:

  1. Verify installation:

    pip show matlab-mcp

    If not found, reinstall: pip install matlab-mcp

  2. Check active Python environment:

    which python
python -c "import matlab_mcp; print(matlab_mcp.__file__)"

  3. Run with explicit Python module:

    python -m matlab_mcp.server

  4. Check for import errors:

    python -c "from matlab_mcp.server import main; main()" --help

    Look for any ImportError or ModuleNotFoundError.

MATLAB Engine startup timeout

Symptom: Engine start timeout after waiting 120+ seconds

Likely Cause: MATLAB taking longer than expected to initialize, network-mapped drives slow, or insufficient system resources.

Solution:

  1. Increase engine startup timeout:

    pool:
  engine_start_timeout: 300  # 5 minutes instead of default 120s

    Or via environment variable:

    export MATLAB_MCP_POOL_ENGINE_START_TIMEOUT=300
matlab-mcp --transport stdio

  2. Test MATLAB startup manually:

    python -c "import matlab.engine; eng = matlab.engine.start_matlab(); print('OK'); eng.quit()"

    If this is slow, the issue is MATLAB itself, not the server.

  3. Check system resources:

    • Disk space: df -h (macOS/Linux) or diskpart list volume (Windows)
    • RAM: top (macOS/Linux) or Task Manager (Windows)
    • If low on either, close other applications or increase available resources.

  4. Disable startup commands if configured (they slow initialization):

    workspace:
  startup_commands: []

  5. On Windows: Network-mapped drives can slow MATLAB startup. Use local paths for temp_dir and result_dir:

    execution:
  temp_dir: "C:\\Users\\YourName\\AppData\\Local\\Temp\\matlab_mcp"

Max engines exceeded on macOS

Symptom: Warning: MATLAB on macOS is limited to ~4 concurrent engines

Likely Cause: Configuration set max_engines higher than macOS limit (4 concurrent instances).

Solution:

  1. Lower max engines to 4:

    pool:
  max_engines: 4

    Or via environment variable:

    export MATLAB_MCP_POOL_MAX_ENGINES=4

  2. Explanation: The MATLAB Engine API on macOS has a built-in limit of ~4 concurrent instances. The server will warn but continue to function with the configured value; you may experience slower performance or hung engines if you exceed 4.

Out of memory errors

Symptom: MemoryError or MATLAB engine crash during code execution

Likely Cause: Large data structures exceeding available MATLAB/system memory, or memory leak in engine pool.

Solution:

  1. Reduce workspace size:

    execution:
  workspace_isolation: true  # Clear after each execution

  2. Lower pool size to reduce baseline memory:

    pool:
  max_engines: 4  # Fewer engines = less baseline memory

  3. Check system memory availability:

    free -h          # Linux
vm_stat          # macOS
Get-ComputerInfo # Windows (PowerShell)

  4. Monitor actual memory usage during execution:

    MATLAB_MCP_MONITORING_ENABLED=true matlab-mcp --transport stdio
# Monitor at http://localhost:8766/dashboard

  5. Optimize MATLAB code: Use sparse matrices, avoid unnecessary copies, delete large variables:

    X = randn(10000, 10000);  % 762 MB
% ... use X ...
clear X                    % Free memory

Configuration

Config file not found

Symptom: FileNotFoundError: config.yaml not found

Likely Cause: Config file not in current working directory or path not specified.

Solution:

  1. Create a config file from the template:

    cat > config.yaml << 'EOF'
server:
  transport: "stdio"
  log_level: "info"

pool:
  min_engines: 1
  max_engines: 4

execution:
  sync_timeout: 30

security:
  blocked_functions_enabled: true
EOF

  2. Specify config path explicitly:

    matlab-mcp --config /path/to/config.yaml

  3. Check current working directory:

    pwd
ls config.yaml

Invalid YAML syntax

Symptom: yaml.YAMLError or yaml.scanner.ScannerError

Likely Cause: Syntax error in config.yaml (indentation, quotes, colons, etc.).

Solution:

  1. Validate YAML syntax:

    python -c "import yaml; yaml.safe_load(open('config.yaml'))"

    If error, the message points to the line with the problem.

  2. Common YAML mistakes:

    • Missing colons after keys: log_level info should be log_level: info
    • Inconsistent indentation: Use spaces (not tabs), typically 2 or 4 per level
    • Unquoted strings with special characters: result_dir: ./results is OK; result_dir: C:\results needs quotes: result_dir: "C:\\results" (Windows)

  3. Use a YAML validator online if unsure: https://www.yamllint.com/

Environment variable not recognized

Symptom: Setting MATLAB_MCP_* environment variable has no effect

Likely Cause: Variable name format incorrect or variable set after server started.

Solution:

  1. Use correct format: MATLAB_MCP_<SECTION>_<KEY>

    export MATLAB_MCP_POOL_MAX_ENGINES=8          # ✓ Correct
export MATLAB_MCP_maxengines=8                # ✗ Wrong (no underscore)
export MATLAB_MCP_POOL_max_engines=8          # ✗ Wrong (inconsistent case)

  2. Verify variable is set:

    echo $MATLAB_MCP_POOL_MAX_ENGINES

  3. Restart server after setting variables:

    export MATLAB_MCP_POOL_MAX_ENGINES=8
matlab-mcp --transport stdio  # New process picks up env var

  4. Check supported sections: Only these support env var overrides:

    • server, pool, execution, sessions, monitoring

    These do NOT (use config file instead):

    • workspace, toolboxes, custom_tools, code_checker, output, security (partial)

Networking (SSE/HTTP Transport)

Connection refused on SSE transport

Symptom: Client gets Connection refused or HTTP 502 when connecting to http://localhost:8765/sse

Likely Cause: Server not listening, wrong port, or firewall blocking.

Solution:

  1. Check server is running:

    ps aux | grep matlab-mcp  # Linux/macOS
tasklist | findstr python # Windows

    If not running, start it:

    matlab-mcp --transport sse

  2. Verify port in config:

    grep port config.yaml

    Default is 8765. Change if needed:

    server:
  port: 9000

  3. Check port is open:

    lsof -i :8765              # macOS/Linux
netstat -ano | findstr :8765 # Windows

    If already in use by another process, either stop that process or change server port.

  4. Firewall blocking (Windows):

    If running Windows with Firewall enabled, allow Python through:

    • Open Windows Defender Firewall
    • Click "Allow an app through firewall"
    • Add Python.exe or matlab-mcp entry

    Or run from elevated prompt (admin) to auto-allow.

  5. Firewall blocking (remote access):

    If connecting remotely to a different machine:

    # On server machine, allow remote access
telnet remote_ip 8765

    If connection refused, the firewall is blocking. Open the port or put behind a reverse proxy.

Bearer token authentication fails

Symptom: HTTP 401 or Unauthorized when connecting over SSE/HTTP

Likely Cause: No token configured, wrong token sent, or auth middleware not active.

Solution:

  1. Generate a token:

    matlab-mcp --generate-token

    Output: export MATLAB_MCP_AUTH_TOKEN="<64-char-hex-token>"

  2. Set the token:

    export MATLAB_MCP_AUTH_TOKEN="<token-from-above>"
matlab-mcp --transport sse

  3. Verify token is set:

    echo $MATLAB_MCP_AUTH_TOKEN

  4. Send token in client request:

    curl:

    curl -H "Authorization: Bearer $MATLAB_MCP_AUTH_TOKEN" http://localhost:8765/health

    Python MCP client:

    import os
from mcp import StreamableHTTPClient

token = os.environ.get("MATLAB_MCP_AUTH_TOKEN")
client = StreamableHTTPClient(
    f"http://localhost:8765/mcp",
    extra_headers={"Authorization": f"Bearer {token}"}
)

  5. Check server logs for auth errors:

    MATLAB_MCP_SERVER_LOG_LEVEL=debug matlab-mcp --transport sse 2>&1 | grep -i auth

CORS errors in browser-based agent

Symptom: Browser console shows CORS policy error or Access-Control-Allow-Origin

Likely Cause: Client request from a different origin (scheme, host, or port) and CORS not configured.

Solution:

  1. Enable CORS for all origins (development only):

    server:
  cors_allowed_origins: "*"

  2. Or specify exact origins:

    server:
  cors_allowed_origins:
    - "http://localhost:3000"
    - "https://app.example.com"

  3. Restart server and test:

    matlab-mcp --transport sse
# Browser request from http://localhost:3000 should now work

Streamable HTTP transport connects but no tools returned

Symptom: Client connects to /mcp but tools/list returns empty list

Likely Cause: Server still using SSE transport config, or tools not registered.

Solution:

  1. Verify transport is streamable HTTP:

    server:
  transport: "streamablehttp"

  2. Restart server and check logs for transport confirmation:

    matlab-mcp --transport streamablehttp 2>&1 | grep -i "HTTP\|streamable"
# Should see: "Streamable HTTP endpoint: http://0.0.0.0:8765/mcp"

  3. Test endpoint directly:

    curl http://localhost:8765/health
# Should return 200 OK with health JSON

  4. List tools directly:

    curl -X POST http://localhost:8765/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

    If tools are missing, check that core tools are registered in server.py.

Security & Execution

Blocked function error on legitimate code

Symptom: BlockedFunctionError: Function 'system' is blocked when trying to run code that needs it

Likely Cause: Function is in the blocklist for safety, but you need it anyway.

Solution:

  1. Check if MATLAB-native alternative exists:

    Blocked Native Alternative
    system() fileread(), readtable(), dir()
    unix() Platform detection: ispc, ismac, isunix
    dos() dos() rarely needed; use file I/O instead
    ! (shell escape) Same as system() — use MATLAB functions
    eval() Use feval() with function handle, or refactor
    evalin() Pass variables as function arguments
    assignin() Use return values instead

  2. If no alternative exists, unblock the function:

    Config file:

    security:
  blocked_functions:
    - "unix"      # Keep these
    - "dos"
    # Remove "system" from the list

    Or via environment variable (limited support):

    # Note: This is less flexible than config file
export MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED=false  # Disables all checks (not recommended)

  3. For production servers with shared access, avoid unblocking — use an allowlist of safe custom tools instead (see Custom Tools).

Code syntax check fails before execution

Symptom: checkcode returns false (red warnings) but code still runs in MATLAB directly

Likely Cause: MATLAB version differences or checkcode settings.

Solution:

  1. Disable auto-check if not needed:

    code_checker:
  enabled: false

  2. Or disable pre-execution check and let code run:

    code_checker:
  auto_check_before_execute: false

  3. View the actual warnings: Ask the server to call check_code as a tool, which returns detailed violations.

Monitoring & Debugging

Enable debug logging

Symptom: Need to see detailed server activity for troubleshooting

Solution:

  1. Update config:

    server:
  log_level: "debug"
  log_file: "./logs/server.log"

  2. Or use environment variable:

    export MATLAB_MCP_SERVER_LOG_LEVEL=debug
matlab-mcp --transport stdio 2>&1 | tee server.log

  3. View logs:

    tail -f ./logs/server.log

  4. Search for specific issues:

    grep -i "error\|exception\|failed" ./logs/server.log

  5. Reduce verbosity after debugging:

    server:
  log_level: "info"  # Back to normal

Collect diagnostic information for bug reports

Symptom: Need to provide detailed system info to the developers.

Solution: Run this diagnostic script and include output in GitHub issue:

#!/bin/bash
echo "=== System Info ==="
python --version
uname -a

echo ""
echo "=== MATLAB Info ==="
matlab -batch "version" -nojvm -nodisplay 2>&1 | head -5

echo ""
echo "=== Python Packages ==="
pip show matlab-mcp fastmcp pydantic

echo ""
echo "=== MATLAB Engine ==="
python -c "import matlab.engine; print('OK')"

echo ""
echo "=== Config File ==="
cat config.yaml

echo ""
echo "=== Server Test ==="
timeout 10 matlab-mcp --transport stdio << 'MATLAB'
disp('Hello')
MATLAB

On Windows (PowerShell):

Write-Host "=== System Info ==="
python --version
$PSVersionTable

Write-Host ""
Write-Host "=== Python Packages ==="
pip show matlab-mcp fastmcp pydantic

Write-Host ""
Write-Host "=== MATLAB ==="
python -c "import matlab.engine; print('OK')"

Write-Host ""
Write-Host "=== Config ==="
Get-Content config.yaml

Include the output when reporting issues.

Still Stuck?

Where to get help

  1. GitHub Issues: https://github.com/HanSur94/matlab-mcp-server-py/issues

    • Search existing issues first
    • Include output from diagnostic script above
    • Minimal reproducible example

  2. Documentation:

  3. Community:

Debugging checklist

Before opening an issue, verify:

  • Python 3.10+ and MATLAB R2022b+ installed
  • MATLAB Engine API imports: python -c "import matlab.engine; print('OK')"
  • Config file exists and valid YAML: python -c "import yaml; yaml.safe_load(open('config.yaml'))"
  • Server starts: matlab-mcp --transport stdio (runs and accepts input)
  • Basic code execution works: disp('Hello') in stdio transport
  • Security checks pass: Try non-blocked code first
  • Logs checked: tail -f ./logs/server.log with log_level: debug

Clone this wiki locally