Skip to content

Configuration

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

Configuration

All settings are in config.yaml with sensible defaults. Every setting can be overridden via environment variables with the MATLAB_MCP_ prefix.

Config File Location

The server looks for config.yaml in the current working directory by default. Override with:

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

Environment Variable Overrides

Any config value can be set via environment variable using the pattern MATLAB_MCP_<SECTION>_<KEY>:

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
export MATLAB_MCP_SERVER_PORT=9000

The environment variable key is converted to lowercase and mapped to config[section][key]. Type coercion is applied automatically: strings are converted to int, float, or bool where applicable.

Note: Multi-word keys are converted using underscores. For example, MATLAB_MCP_EXECUTION_SYNC_TIMEOUT becomes execution.sync_timeout.

Full Configuration Reference

Server

Controls transport, logging, and result storage.

server:
  name: "matlab-mcp-server"        # Server name reported to MCP clients
  transport: "stdio"               # stdio | sse
  host: "0.0.0.0"                  # Bind address (SSE transport only)
  port: 8765                        # Listen port (SSE transport only)
  log_level: "info"                 # debug | info | warning | error
  log_file: "./logs/server.log"     # Log file path (resolved to absolute)
  result_dir: "./results"           # Directory for result files (resolved to absolute)
  drain_timeout_seconds: 300        # Max wait for running jobs during graceful shutdown
Field Type Default Notes
name string "matlab-mcp-server" Reported to MCP clients
transport stdio | sse "stdio" Transport protocol
host string "0.0.0.0" Only used if transport is sse
port integer 8765 Only used if transport is sse
log_level string "info" Controls verbosity
log_file string "./logs/server.log" Relative paths resolved to absolute
result_dir string "./results" Relative paths resolved to absolute
drain_timeout_seconds integer 300 Shutdown grace period

Environment overrides:

  • MATLAB_MCP_SERVER_NAME
  • MATLAB_MCP_SERVER_TRANSPORT
  • MATLAB_MCP_SERVER_HOST
  • MATLAB_MCP_SERVER_PORT
  • MATLAB_MCP_SERVER_LOG_LEVEL
  • MATLAB_MCP_SERVER_LOG_FILE
  • MATLAB_MCP_SERVER_RESULT_DIR
  • MATLAB_MCP_SERVER_DRAIN_TIMEOUT_SECONDS

Pool

Configures MATLAB engine pooling and resource management.

pool:
  min_engines: 2                    # Always keep this many engines warm
  max_engines: 10                   # Hard ceiling (capped at 4 on macOS)
  scale_down_idle_timeout: 900      # Seconds idle before scaling down (15 min)
  engine_start_timeout: 120         # Seconds to wait for MATLAB to start
  health_check_interval: 60         # Seconds between health pings
  proactive_warmup_threshold: 0.8   # Utilization ratio to trigger warmup
  queue_max_size: 50                # Max pending requests in queue
  matlab_root: null                 # Auto-detect, or set explicit MATLAB path
Field Type Default Notes
min_engines integer 2 Must be ≤ max_engines
max_engines integer 10 Capped at 4 on macOS if higher
scale_down_idle_timeout integer 900 Idle seconds before engine shutdown
engine_start_timeout integer 120 Timeout for MATLAB startup
health_check_interval integer 60 Seconds between pings
proactive_warmup_threshold float 0.8 Utilization ratio (0.0–1.0)
queue_max_size integer 50 Max queued requests
matlab_root string | null null Explicit MATLAB path or auto-detect

Environment overrides:

  • MATLAB_MCP_POOL_MIN_ENGINES
  • MATLAB_MCP_POOL_MAX_ENGINES
  • MATLAB_MCP_POOL_SCALE_DOWN_IDLE_TIMEOUT
  • MATLAB_MCP_POOL_ENGINE_START_TIMEOUT
  • MATLAB_MCP_POOL_HEALTH_CHECK_INTERVAL
  • MATLAB_MCP_POOL_PROACTIVE_WARMUP_THRESHOLD
  • MATLAB_MCP_POOL_QUEUE_MAX_SIZE
  • MATLAB_MCP_POOL_MATLAB_ROOT

macOS Note: MATLAB on macOS has a 4-engine limit. The server will log a warning if max_engines > 4 on macOS but still respects the configured value. For stability, set max_engines <= 4 on macOS.

Execution

Controls job execution behavior and workspace management.

execution:
  sync_timeout: 30                  # Seconds before auto-promoting to async
  max_execution_time: 86400         # Hard limit per job (24h = 86400s)
  workspace_isolation: true         # Clear workspace between sessions
  engine_affinity: false            # Pin session to specific engine
  temp_dir: "./temp"                # Temporary file directory (resolved to absolute)
  temp_cleanup_on_disconnect: true  # Delete temp files when session ends
Field Type Default Notes
sync_timeout integer 30 Seconds before auto-promoting to async
max_execution_time integer 86400 Hard limit per job in seconds
workspace_isolation boolean true Clear workspace between sessions
engine_affinity boolean false Pin session to engine for persistence
temp_dir string "./temp" Relative paths resolved to absolute
temp_cleanup_on_disconnect boolean true Clean up temp files on disconnect

Environment overrides:

  • MATLAB_MCP_EXECUTION_SYNC_TIMEOUT
  • MATLAB_MCP_EXECUTION_MAX_EXECUTION_TIME
  • MATLAB_MCP_EXECUTION_WORKSPACE_ISOLATION
  • MATLAB_MCP_EXECUTION_ENGINE_AFFINITY
  • MATLAB_MCP_EXECUTION_TEMP_DIR
  • MATLAB_MCP_EXECUTION_TEMP_CLEANUP_ON_DISCONNECT

sync_timeout: When code runs longer than this threshold, the server automatically promotes it to an async job and returns a job_id for polling. Increase this for environments where most code is expected to take 30–60 seconds.

Workspace

Configures MATLAB path and startup behavior.

workspace:
  default_paths:                    # Added to MATLAB path on engine start/reset
    - "/shared/custom_libs"
    - "/shared/data"
  startup_commands:                 # Run on each engine start and after workspace reset
    - "format long"
Field Type Default Notes
default_paths list of strings [] Added to MATLAB path automatically
startup_commands list of strings ["format long"] Executed on engine start

Environment overrides: Multi-item lists cannot be overridden via environment variables. Use the config file for workspace settings.

Toolboxes

Controls which MATLAB toolboxes are reported to agents.

toolboxes:
  mode: "whitelist"                 # whitelist | blacklist | all
  list:
    - "Signal Processing Toolbox"
    - "Optimization Toolbox"
    - "Statistics and Machine Learning Toolbox"
    - "Image Processing Toolbox"
Field Type Default Notes
mode whitelist | blacklist | all "whitelist" Toolbox filtering mode
list list of strings [] Toolbox names
Mode Behavior
whitelist Only listed toolboxes are reported to agents
blacklist All toolboxes EXCEPT listed ones are reported
all All installed toolboxes are reported

Environment overrides:

  • MATLAB_MCP_TOOLBOXES_MODE (for the mode only; list requires config file)

Custom Tools

Configures external custom tools via a separate YAML file.

custom_tools:
  config_file: "./custom_tools.yaml"
Field Type Default Notes
config_file string "./custom_tools.yaml" Path to custom tools YAML (resolved to absolute)

Environment overrides:

  • MATLAB_MCP_CUSTOM_TOOLS_CONFIG_FILE

See the Custom Tools documentation for the full custom tools format.

Security

Controls function blocking and upload size limits.

security:
  blocked_functions_enabled: true
  blocked_functions:
    - "system"
    - "unix"
    - "dos"
    - "!"
    - "eval"
    - "feval"
    - "evalc"
    - "evalin"
    - "assignin"
    - "perl"
    - "python"
  max_upload_size_mb: 100
  require_proxy_auth: false
Field Type Default Notes
blocked_functions_enabled boolean true Enable function blocking
blocked_functions list of strings (see above) MATLAB functions to block
max_upload_size_mb integer 100 Max upload size in MB
require_proxy_auth boolean false Set true for production SSE behind auth proxy

Environment overrides:

  • MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED
  • MATLAB_MCP_SECURITY_MAX_UPLOAD_SIZE_MB
  • MATLAB_MCP_SECURITY_REQUIRE_PROXY_AUTH

blocked_functions: These MATLAB functions are blocked from execution. The security validator strips string literals and comments before scanning, so disp('system') won't trigger a false positive.

Code Checker

Configures MATLAB code checking and validation.

code_checker:
  enabled: true
  auto_check_before_execute: false
  severity_levels: ["error", "warning"]
Field Type Default Notes
enabled boolean true Enable code checker
auto_check_before_execute boolean false Run checkcode before execution
severity_levels list of strings ["error", "warning"] Severity levels to report

Environment overrides:

  • MATLAB_MCP_CODE_CHECKER_ENABLED
  • MATLAB_MCP_CODE_CHECKER_AUTO_CHECK_BEFORE_EXECUTE

Output

Configures result rendering and file thresholds.

output:
  plotly_conversion: true           # Convert MATLAB figures to Plotly JSON
  static_image_format: "png"        # png | jpg | svg
  static_image_dpi: 150
  thumbnail_enabled: true
  thumbnail_max_width: 400
  large_result_threshold: 10000     # Elements — save large results to file
  max_inline_text_length: 50000     # Chars — save long text to file
Field Type Default Notes
plotly_conversion boolean true Convert figures to Plotly JSON
static_image_format png | jpg | svg "png" Static image format
static_image_dpi integer 150 DPI for static images
thumbnail_enabled boolean true Generate thumbnails
thumbnail_max_width integer 400 Max thumbnail width in pixels
large_result_threshold integer 10000 Element count threshold for file saving
max_inline_text_length integer 50000 Character count threshold for text file saving

Environment overrides:

  • MATLAB_MCP_OUTPUT_PLOTLY_CONVERSION
  • MATLAB_MCP_OUTPUT_STATIC_IMAGE_FORMAT
  • MATLAB_MCP_OUTPUT_STATIC_IMAGE_DPI
  • MATLAB_MCP_OUTPUT_THUMBNAIL_ENABLED
  • MATLAB_MCP_OUTPUT_THUMBNAIL_MAX_WIDTH
  • MATLAB_MCP_OUTPUT_LARGE_RESULT_THRESHOLD
  • MATLAB_MCP_OUTPUT_MAX_INLINE_TEXT_LENGTH

Sessions

Configures session lifecycle and job retention.

sessions:
  max_sessions: 50
  session_timeout: 3600             # Seconds of inactivity before cleanup (1h)
  job_retention_seconds: 86400      # Keep completed job metadata for 24h
Field Type Default Notes
max_sessions integer 50 Max concurrent sessions
session_timeout integer 3600 Inactivity timeout in seconds
job_retention_seconds integer 86400 Job metadata retention in seconds

Environment overrides:

  • MATLAB_MCP_SESSIONS_MAX_SESSIONS
  • MATLAB_MCP_SESSIONS_SESSION_TIMEOUT
  • MATLAB_MCP_SESSIONS_JOB_RETENTION_SECONDS

Monitoring

Configures metrics collection and dashboard.

monitoring:
  enabled: true
  sample_interval: 10               # Seconds between metric samples
  retention_days: 7                 # Days to keep historical data
  db_path: "./monitoring/metrics.db" # SQLite database path (resolved to absolute)
  dashboard_enabled: true           # Enable web dashboard
  http_port: 8766                   # Dashboard port (stdio transport only)
Field Type Default Notes
enabled boolean true Enable metrics collection
sample_interval integer 10 Seconds between samples
retention_days integer 7 Days to retain historical data
db_path string "./monitoring/metrics.db" SQLite database path (resolved to absolute)
dashboard_enabled boolean true Enable web dashboard
http_port integer 8766 Dashboard port (stdio transport only)

Environment overrides:

  • MATLAB_MCP_MONITORING_ENABLED
  • MATLAB_MCP_MONITORING_SAMPLE_INTERVAL
  • MATLAB_MCP_MONITORING_RETENTION_DAYS
  • MATLAB_MCP_MONITORING_DB_PATH
  • MATLAB_MCP_MONITORING_DASHBOARD_ENABLED
  • MATLAB_MCP_MONITORING_HTTP_PORT

Note: Monitoring requires optional dependencies (psutil, uvicorn). Install with:

pip install -e ".[monitoring]"
# or pip install -e ".[dev]"  (dev includes monitoring dependencies)

Example Configurations

See the examples/ directory for ready-to-use configurations:

  • config_minimal.yaml — Single user, minimal settings
  • config_multiuser.yaml — Multi-user SSE with larger pool and stricter security

Clone this wiki locally