Skip to content

Troubleshooting

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

Troubleshooting

Welcome to the MATLAB MCP Server troubleshooting guide. This page helps you diagnose and resolve common issues.

Quick Navigation

Installation & Setup

MATLAB Engine API Not Found

Symptoms:

  • ModuleNotFoundError: No module named 'matlab'
  • ImportError: matlab.engine not found
  • Server fails to start with message about MATLAB installation

Likely Causes:

  • MATLAB Engine API for Python is not installed
  • Wrong MATLAB version (server requires R2022b or later)
  • Python path doesn't include MATLAB installation

Solutions:

  1. Verify MATLAB is installed:

    which matlab  # macOS/Linux
where matlab  # Windows

  2. Install the MATLAB Engine API:

    macOS:

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

    Windows:

    cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"
pip install .

    Linux:

    cd /usr/local/MATLAB/R2024a/extern/engines/python
pip install .

  3. Verify installation succeeded:

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

  4. Check MATLAB version:

    matlab -r "version; exit"

    Must be R2022b or later.

  5. Set MATLAB root explicitly (if auto-detection fails):

    # config.yaml
pool:
  matlab_root: "/Applications/MATLAB_R2024a.app"  # macOS
  # matlab_root: "C:\\Program Files\\MATLAB\\R2024a"  # Windows

    Or via environment variable:

    export MATLAB_MCP_POOL_MATLAB_ROOT=/Applications/MATLAB_R2024a.app

Python Version Incompatibility

Symptoms:

  • ERROR: Package requires Python >=3.10
  • Cryptic import errors or syntax errors on startup

Solutions:

  1. Check your Python version:

    python --version

  2. Install Python 3.10 or later:

    • Official Python.org downloads
    • macOS: brew install python@3.12
    • Ubuntu: sudo apt-get install python3.12
    • Windows: Use the official installer (don't forget to add to PATH)

  3. Use a virtual environment with the correct version:

    python3.12 -m venv venv
source venv/bin/activate  # macOS/Linux
# or: venv\Scripts\activate  # Windows
pip install matlab-mcp-python

Package Installation Fails

Symptoms:

  • pip install matlab-mcp-python fails with network or compilation errors
  • Wheel build fails with C extension errors

Likely Causes:

  • Network connectivity issues
  • Missing build tools (on Windows or Linux)
  • Conflicting dependency versions

Solutions:

  1. Retry with verbose output:

    pip install -v matlab-mcp-python

  2. Upgrade pip, setuptools, and wheel:

    pip install --upgrade pip setuptools wheel
pip install matlab-mcp-python

  3. Install from source (offline):

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

  4. Use conda (often more reliable for dependencies):

    conda env create -f environment.yml
conda activate matlab-mcp

Runtime Errors

MATLAB Engine Startup Timeout

Symptoms:

  • Engine start timeout after Xs
  • Server starts but hangs indefinitely
  • Only affects first request

Likely Causes:

  • MATLAB is slow to initialize (especially on older hardware)
  • MATLAB license server is unreachable
  • MATLAB is hung or locked by another process

Solutions:

  1. Increase the startup timeout:

    # config.yaml
pool:
  engine_start_timeout: 300  # 5 minutes (default is 60)

    Or via environment variable:

    export MATLAB_MCP_POOL_ENGINE_START_TIMEOUT=300

  2. Verify MATLAB can start manually:

    matlab -r "disp('MATLAB started'); exit"

  3. Check MATLAB license:

    matlab -r "license('test','Symbolic_Math_Toolbox'); exit"

  4. Kill hung MATLAB processes:

    pkill -f "MATLAB"  # macOS/Linux
taskkill /F /IM MATLAB.exe  # Windows

  5. Check disk space:

    df -h  # macOS/Linux
# Windows: Right-click drive → Properties

    MATLAB needs free space for temp files.

Max Engine Limit Exceeded (macOS)

Symptoms:

  • Warning: Too many MATLAB engines requested. macOS limit is ~4 concurrent
  • Jobs fail with "insufficient engines available"

Explanation:

  • macOS has a hard limit of ~4 simultaneous MATLAB engines due to OS constraints
  • This is a platform limitation, not a bug

Solutions:

  1. Set max engines to 4:

    # config.yaml
pool:
  min_engines: 2
  max_engines: 4  # macOS limit

  2. Reduce concurrent load:

    • Encourage long-running jobs to use async execution (mcp_progress())
    • Configure session timeouts to free resources: sessions.idle_timeout: 300

  3. Consider Linux deployment for higher parallelism

Out of Memory Error

Symptoms:

  • MemoryError or Java heap out of memory
  • Killed: 9 (OOM killer on Linux)
  • Performance suddenly drops

Likely Causes:

  • Large variable assignments in MATLAB workspace
  • Memory leak in long-running jobs
  • Too many concurrent engines for available RAM

Solutions:

  1. Monitor memory usage:

    # During server operation, in another terminal:
top -p $(pgrep -f "matlab")  # macOS/Linux
# or Task Manager on Windows

  2. Reduce max engines:

    pool:
  max_engines: 4  # Reduce from default 10

  3. Reduce max sessions:

    sessions:
  max_sessions: 5  # Fewer concurrent users

  4. Enable workspace clearing between jobs:

    execution:
  clear_workspace_after_job: true

  5. Increase system swap (last resort):

    # Linux only
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Connection Issues

Client Can't Connect (stdio transport)

Symptoms:

  • Client says "connection refused" or "no server running"
  • matlab-mcp starts but client sees nothing
  • Claude Desktop says "Tool use requires connection"

Likely Causes:

  • Server crashed silently (no MATLAB engine)
  • Server started but not in stdio mode
  • Another process using stdio

Solutions:

  1. Verify server is running:

    matlab-mcp &
# Should print banner and wait for input

  2. Check MATLAB Engine API:

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

  3. Run with verbose logging:

    MATLAB_MCP_SERVER_LOG_LEVEL=debug matlab-mcp

  4. Use SSE transport instead (if stdio fails):

    matlab-mcp --transport sse
# Now connect client to http://localhost:8765/sse

HTTP/SSE Connection Refused

Symptoms:

  • Connection refused when accessing http://localhost:8765/sse
  • ERR_CONNECTION_REFUSED in browser
  • Client times out

Likely Causes:

  • Server not started with --transport sse
  • Firewall blocking port 8765
  • Wrong host/port configuration
  • Server crashed on startup

Solutions:

  1. Verify server is running:

    matlab-mcp --transport sse
# Look for "SSE endpoint available at http://localhost:8765/sse"

  2. Check the port is listening:

    netstat -tuln | grep 8765  # macOS/Linux
netstat -ano | findstr :8765  # Windows

  3. Try localhost vs 127.0.0.1:

    curl -i http://127.0.0.1:8765/health
# Should return 200 OK

  4. Disable firewall temporarily to test:

    # macOS
sudo /usr/libexec/ApplicationFirewall/socketfilterfw -setglobalstate off

# Linux (ufw)
sudo ufw disable

# Windows: Disable Windows Defender Firewall temporarily

  5. Check logs:

    tail -f server.log  # If logging to file

Bearer Token Authentication Fails

Symptoms:

  • HTTP 401 Unauthorized on every request
  • WWW-Authenticate: Bearer realm="MATLAB MCP Server"
  • Client says "Invalid token"

Likely Causes:

  • Token not set in environment variable
  • Token format incorrect
  • Typo in bearer token header
  • Server restarted with different token

Solutions:

  1. Generate a valid token:

    matlab-mcp --generate-token
# Outputs: 64-char hex token + env var snippets

  2. Set the token before starting server:

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

  3. Verify token is set:

    echo $MATLAB_MCP_AUTH_TOKEN  # Should print the token

  4. Test with curl:

    curl -H "Authorization: Bearer $MATLAB_MCP_AUTH_TOKEN" \
     http://localhost:8765/health
# Should return 200 OK, not 401

  5. Check token has not changed:

    • If server was restarted, the token must match the client's environment
    • Tokens don't persist across sessions; store in .env file or GitHub secret

Remote Client Connection Timeout

Symptoms:

  • Client can reach server (IP/port is open)
  • Connection starts but hangs or times out
  • No error message, just waits forever

Likely Causes:

  • Network latency or packet loss
  • Firewall blocking MCP handshake
  • Server is overloaded
  • Wrong transport or endpoint

Solutions:

  1. Test basic connectivity:

    ping <server-ip>  # Should see replies

  2. Test HTTP endpoint:

    curl -v http://<server-ip>:8765/health
# Should return 200 OK quickly

  3. Check network MTU (if very slow):

    # Linux/macOS
ping -D -s 1472 <server-ip>  # Test MTU

  4. Reduce request timeout on client:

    • Some agents have connection timeouts (30-60s default)
    • Ensure server responds within client timeout

Configuration Problems

Config File Not Found

Symptoms:

  • Warning: Config file not found: ./config.yaml, using defaults
  • Server starts with defaults instead of custom config

Likely Causes:

  • File not in current working directory
  • Typo in filename
  • File permissions issue

Solutions:

  1. Create config file:

    cp examples/config_minimal.yaml config.yaml
# or
matlab-mcp --help  # Shows default config

  2. Specify config path:

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

  3. Check current directory:

    pwd  # Print working directory
ls -la config.yaml  # Verify file exists and is readable

  4. Check file permissions:

    chmod 644 config.yaml  # Make readable by server process

YAML Parse Error

Symptoms:

  • yaml.YAMLError: mapping values are not allowed here
  • yaml.scanner.ScannerError: expected <block end>
  • Invalid YAML syntax error with line number

Likely Causes:

  • Tabs instead of spaces (YAML requires spaces)
  • Quote mismatch
  • Invalid indentation
  • Special characters not escaped

Solutions:

  1. Validate YAML syntax:

    python -c "import yaml; yaml.safe_load(open('config.yaml'))"
# If no error, YAML is valid

  2. Use an online validator:

  3. Fix common issues:

    • Replace tabs with spaces (Python style)
    • Quote strings with special characters: "value: 123"
    • Check indentation is consistent (2 or 4 spaces)

  4. Example valid config:

    server:
  transport: "stdio"
  log_level: "info"

pool:
  min_engines: 2
  max_engines: 10

Environment Variable Override Not Working

Symptoms:

  • Set MATLAB_MCP_POOL_MAX_ENGINES=5 but server uses default (10)
  • Environment variables seem to be ignored

Likely Causes:

  • Variable name typo
  • Variable not exported
  • Config file override takes precedence

Solutions:

  1. Verify variable is set:

    echo $MATLAB_MCP_POOL_MAX_ENGINES
# Should print: 5

  2. Export the variable (if not already exported):

    export MATLAB_MCP_POOL_MAX_ENGINES=5
matlab-mcp

  3. Check the prefix: Must be MATLAB_MCP_ followed by section and key in uppercase with underscores:

    # Correct:
export MATLAB_MCP_POOL_MAX_ENGINES=5
export MATLAB_MCP_SERVER_HOST=127.0.0.1

# Incorrect:
export MAX_ENGINES=5  # Missing prefix
export POOL_MAX_ENGINES=5  # Missing prefix

  4. Verify config file isn't overriding:

    • If config.yaml has explicit values, env vars may not override
    • Delete config.yaml to use env vars only

Blocked Function Not In Blocklist

Symptoms:

  • Want to block a function (e.g., eval) but it's not in default blocklist
  • Or a legitimate function (e.g., system) is blocked and you need to remove it

Likely Causes:

  • Blocklist configuration is incomplete
  • Default blocklist too strict for your use case

Solutions:

  1. Add to blocklist:

    # config.yaml
security:
  blocked_functions:
    - system
    - eval
    - disp  # New addition

  2. Remove from blocklist:

    # config.yaml
security:
  blocked_functions:
    - system
    - eval
    # - disp  # Removed (commented out)

  3. Disable blocklist entirely (not recommended):

    security:
  blocked_functions_enabled: false

  4. View current blocklist:

    matlab-mcp --help  # Shows default config with blocked functions

Networking & Security

Firewall Blocking Port

Symptoms:

  • Server runs on http://localhost:8765
  • Remote client can't connect: "Connection refused"
  • netstat shows port is listening but unreachable

Likely Causes:

  • Windows Firewall or macOS firewall blocking inbound
  • Corporate firewall or proxy
  • Port < 1024 requires admin rights (Windows)

Solutions:

  1. Allow port through Windows Firewall:

    # Run as Administrator:
New-NetFirewallRule -DisplayName "MATLAB MCP" -Direction Inbound `
  -Action Allow -LocalPort 8765 -Protocol TCP

  2. Allow through macOS firewall:

    • System Preferences → Security & Privacy → Firewall Options
    • Add python to the allowed list

  3. Use port 80 or 443 (requires admin):

    sudo matlab-mcp --port 80 --transport sse

  4. Use reverse proxy (nginx/Apache) to forward traffic:

    server {
    listen 443 ssl;
    location / {
        proxy_pass http://127.0.0.1:8765;
    }
}

Bearer Token Leaked in Config File

Symptoms:

  • Warning: Possible sensitive key 'token' in config section 'server'
  • Token appears in git history or logs
  • Security audit flags hardcoded credentials

Likely Causes:

  • Token stored directly in config.yaml instead of env var
  • Config file committed to version control
  • Token logged at startup

Solutions:

  1. Use environment variables, not config files:

    export MATLAB_MCP_AUTH_TOKEN="<your-token>"
matlab-mcp  # Don't put token in config.yaml

  2. Generate a new token:

    matlab-mcp --generate-token
# Output: use in MATLAB_MCP_AUTH_TOKEN env var

  3. Add config.yaml to .gitignore:

    echo "config.yaml" >> .gitignore
git rm --cached config.yaml  # Remove from history

  4. Rotate token if compromised:

    matlab-mcp --generate-token  # New token
export MATLAB_MCP_AUTH_TOKEN="<new-token>"
# Restart server with new token

Server Accessible from Outside Network (Unintended)

Symptoms:

  • Server binding to 0.0.0.0 (all interfaces)
  • Anyone on the network can access /health and execute MATLAB code
  • No authentication in place

Likely Causes:

  • server.host set to 0.0.0.0 (broadcast)
  • No bearer token configured
  • SSE endpoint accessible without auth

Solutions:

  1. Bind to localhost only:

    # config.yaml
server:
  host: "127.0.0.1"  # Localhost only

    Or via env var:

    export MATLAB_MCP_SERVER_HOST=127.0.0.1

  2. Enable bearer token authentication:

    matlab-mcp --generate-token
# Copy token to MATLAB_MCP_AUTH_TOKEN env var
matlab-mcp --transport sse

  3. Use a reverse proxy with authentication:

    # nginx.conf
location / {
    auth_basic "MATLAB MCP";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:8765;
}

Debugging & Diagnostics

Enable Debug Logging

To see detailed operation logs:

  1. Set log level in config:

    # config.yaml
server:
  log_level: "debug"
  log_file: "./logs/server.log"  # Optional: write to file

  2. Or use environment variable:

    export MATLAB_MCP_SERVER_LOG_LEVEL=debug
matlab-mcp --transport sse

  3. Monitor logs in real-time:

    tail -f logs/server.log  # If writing to file

  4. Log levels (in order of verbosity):

    • debug — Very detailed, includes all decisions
    • info — Normal operation, key events
    • warning — Potential issues, security warnings
    • error — Failures and exceptions
    • critical — Fatal errors only

Collect Diagnostic Information

When reporting a bug, collect this information:

# 1. Server version
pip show matlab-mcp-python | grep Version

# 2. Python version
python --version

# 3. MATLAB version
matlab -r "version; exit"

# 4. MATLAB Engine API verification
python -c "import matlab.engine; print(matlab.engine.find_matlab())"

# 5. Config validation
python -c "from matlab_mcp.config import load_config; load_config()"

# 6. Last 50 lines of logs
tail -50 logs/server.log > /tmp/server_logs.txt

# 7. System info
uname -a  # macOS/Linux
wmic os get osversion  # Windows

# 8. Available disk space
df -h  # macOS/Linux
# Windows: dir C: (check free space)

Inspect Server State

While server is running:

  1. Check health endpoint:

    curl http://127.0.0.1:8765/health | python -m json.tool
# Shows: uptime, engine count, active jobs, sessions

  2. View metrics dashboard:

    • Open browser to http://127.0.0.1:8766 (if monitoring enabled)
    • Shows pool utilization, job history, error rate

  3. Check job status:

    % Inside Claude conversation, ask:
% "Show me the pool status"
% Server will return current engine availability

Test Connectivity

graph TD
    A["Test Checklist"] --> B["Can Python import matlab.engine?"]
    B -->|Yes| C["Can server start?"]
    B -->|No| D["Fix MATLAB Engine API installation"]
    C -->|Yes| E["Can client connect?"]
    C -->|No| F["Check logs for startup error"]
    E -->|Yes| G["✓ Server working"]
    E -->|No| H["Check firewall, host/port config"]
    H --> I["Enable debug logging"]
    I --> J["Check logs for connection error"]
Loading

Still Stuck?

If you've tried everything above:

  1. Check the project wiki for more detailed docs:

  2. Search existing GitHub issues:

  3. Open a new issue with:

    • Error message and symptoms
    • Your platform (Windows/macOS/Linux) and versions
    • Config file (redact any tokens)
    • Debug logs (see "Collect Diagnostic Information" above)
    • Steps to reproduce

  4. Join community discussions:

  5. Contact maintainer:

Last updated: 2026-04-03 (v2.0 release)

Clone this wiki locally