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
export MATLAB_MCP_OUTPUT_STATIC_IMAGE_FORMAT=svg
export MATLAB_MCP_SESSIONS_MAX_SESSIONS=100

Note: The section name is determined by splitting on the first underscore after MATLAB_MCP_. This means single-word sections work as expected (e.g., MATLAB_MCP_POOL_MAX_ENGINES → pool.max_engines), but multi-word section names like code_checker or custom_tools must use underscores in the environment variable (e.g., MATLAB_MCP_CODE_CHECKER_ENABLED or MATLAB_MCP_CUSTOM_TOOLS_CONFIG_FILE). Use the config file for complex nested overrides.

Full Configuration Reference

Server

Controls the MCP server's name, transport layer, logging, and graceful shutdown behavior.

Field	Type	Default	Description
`name`	string	`"matlab-mcp-server"`	Server name reported to MCP clients
`transport`	`"stdio"` \| `"sse"`	`"stdio"`	Communication protocol: `stdio` for stdin/stdout, `sse` for HTTP Server-Sent Events
`host`	string	`"0.0.0.0"`	Bind address for HTTP listener (SSE transport only)
`port`	integer	`8765`	HTTP port (SSE transport only)
`log_level`	`"debug"` \| `"info"` \| `"warning"` \| `"error"`	`"info"`	Logging verbosity level
`log_file`	string	`"./logs/server.log"`	Log file path (resolved to absolute path at startup)
`result_dir`	string	`"./results"`	Directory for storing result files (resolved to absolute path at startup)
`drain_timeout_seconds`	integer	`300`	Maximum wait time in seconds for running jobs during graceful shutdown

Environment Variable 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

server:
  name: "matlab-mcp-server"
  transport: "stdio"
  host: "0.0.0.0"
  port: 8765
  log_level: "info"
  log_file: "./logs/server.log"
  result_dir: "./results"
  drain_timeout_seconds: 300

Pool

Configures MATLAB engine pool sizing, startup, health checks, and workspace management.

Field	Type	Default	Description
`min_engines`	integer	`2`	Minimum number of MATLAB engines to keep warm
`max_engines`	integer	`10`	Maximum number of MATLAB engines (capped at 4 on macOS)
`scale_down_idle_timeout`	integer	`900`	Seconds of idle time before scaling down to `min_engines`
`engine_start_timeout`	integer	`120`	Seconds to wait for MATLAB process to start and connect
`health_check_interval`	integer	`60`	Seconds between engine health check pings
`proactive_warmup_threshold`	float	`0.8`	Utilization ratio (0.0–1.0) that triggers preemptive engine startup
`queue_max_size`	integer	`50`	Maximum number of pending requests allowed in the execution queue
`matlab_root`	string \| null	`null`	Explicit MATLAB installation path; if null, auto-detect

Environment Variable 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 due to platform constraints. The server will log a warning if max_engines > 4 on macOS but will still attempt to respect the configured value.

pool:
  min_engines: 2
  max_engines: 10
  scale_down_idle_timeout: 900
  engine_start_timeout: 120
  health_check_interval: 60
  proactive_warmup_threshold: 0.8
  queue_max_size: 50
  matlab_root: null

Execution

Controls code execution behavior, timeouts, workspace isolation, and temporary file management.

Field	Type	Default	Description
`sync_timeout`	integer	`30`	Seconds before auto-promoting long-running code to async job
`max_execution_time`	integer	`86400`	Hard limit in seconds per job (24 hours = 86400 seconds)
`workspace_isolation`	boolean	`true`	Clear workspace variables between sessions for isolation
`engine_affinity`	boolean	`false`	Pin session to a specific engine for workspace persistence across requests
`temp_dir`	string	`"./temp"`	Temporary file directory (resolved to absolute path at startup)
`temp_cleanup_on_disconnect`	boolean	`true`	Automatically delete session temp files when client disconnects

Environment Variable 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 Guidance: 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 or longer.

execution:
  sync_timeout: 30
  max_execution_time: 86400
  workspace_isolation: true
  engine_affinity: false
  temp_dir: "./temp"
  temp_cleanup_on_disconnect: true

Workspace

Configures MATLAB path and startup commands for all engines.

Field	Type	Default	Description
`default_paths`	string array	`[]`	Directories to add to MATLAB path on engine start and after workspace reset
`startup_commands`	string array	`["format long"]`	MATLAB commands to run on each engine start and after workspace reset

Environment Variable Overrides:

Multi-element arrays like default_paths and startup_commands are not overridable via environment variables. Use the config file instead.

workspace:
  default_paths:
    - "/shared/custom_libs"
    - "/shared/data"
  startup_commands:
    - "format long"

Toolboxes

Controls which MATLAB toolboxes are reported to agents.

Field	Type	Default	Description
`mode`	`"whitelist"` \| `"blacklist"` \| `"all"`	`"whitelist"`	Toolbox filtering mode
`list`	string array	`[]`	Toolbox names to include (whitelist) or exclude (blacklist)

Environment Variable Overrides:

MATLAB_MCP_TOOLBOXES_MODE
MATLAB_MCP_TOOLBOXES_LIST (not recommended for arrays; use config file)

Mode	Behavior
`whitelist`	Only toolboxes in `list` are reported to agents
`blacklist`	All installed toolboxes EXCEPT those in `list` are reported
`all`	All installed toolboxes are reported (ignore `list`)

toolboxes:
  mode: "whitelist"
  list:
    - "Signal Processing Toolbox"
    - "Optimization Toolbox"
    - "Statistics and Machine Learning Toolbox"
    - "Image Processing Toolbox"

Custom Tools

Specifies the location of custom tools configuration.

Field	Type	Default	Description
`config_file`	string	`"./custom_tools.yaml"`	Path to custom tools YAML file (resolved to absolute path at startup)

Environment Variable Overrides:

MATLAB_MCP_CUSTOM_TOOLS_CONFIG_FILE

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

custom_tools:
  config_file: "./custom_tools.yaml"

Security

Controls function blocking, file upload limits, and authentication requirements.

Field	Type	Default	Description
`blocked_functions_enabled`	boolean	`true`	Enable/disable function blocking validation
`blocked_functions`	string array	See below	MATLAB functions forbidden from execution
`max_upload_size_mb`	integer	`100`	Maximum file upload size in megabytes
`require_proxy_auth`	boolean	`false`	Set to `true` if SSE is behind an authentication proxy

Environment Variable Overrides:

MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED
MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS (not recommended for arrays; use config file)
MATLAB_MCP_SECURITY_MAX_UPLOAD_SIZE_MB
MATLAB_MCP_SECURITY_REQUIRE_PROXY_AUTH

Blocked Functions (Default List): The security validator strips string literals and comments before scanning, so expressions like disp('system') will not trigger false positives.

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

Code Checker

Configures MATLAB code checking and validation.

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable code checker feature
`auto_check_before_execute`	boolean	`false`	Automatically run `checkcode()` before every execution
`severity_levels`	string array	`["error", "warning"]`	Report messages of these severity levels

Environment Variable Overrides:

MATLAB_MCP_CODE_CHECKER_ENABLED
MATLAB_MCP_CODE_CHECKER_AUTO_CHECK_BEFORE_EXECUTE
MATLAB_MCP_CODE_CHECKER_SEVERITY_LEVELS (not recommended for arrays; use config file)

code_checker:
  enabled: true
  auto_check_before_execute: false
  severity_levels: ["error", "warning"]

Output

Controls result formatting, visualization, and size thresholds for saving large results.

Field	Type	Default	Description
`plotly_conversion`	boolean	`true`	Convert MATLAB figures to interactive Plotly JSON format
`static_image_format`	`"png"` \| `"jpg"` \| `"svg"`	`"png"`	Format for static image exports
`static_image_dpi`	integer	`150`	DPI for static image rendering
`thumbnail_enabled`	boolean	`true`	Generate thumbnails for large plots
`thumbnail_max_width`	integer	`400`	Maximum width in pixels for thumbnail generation
`large_result_threshold`	integer	`10000`	Element count above which tabular/matrix data is saved to file
`max_inline_text_length`	integer	`50000`	Character count above which text output is saved to file

Environment Variable 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

output:
  plotly_conversion: true
  static_image_format: "png"
  static_image_dpi: 150
  thumbnail_enabled: true
  thumbnail_max_width: 400
  large_result_threshold: 10000
  max_inline_text_length: 50000

Sessions

Controls session lifecycle and job metadata retention.

Field	Type	Default	Description
`max_sessions`	integer	`50`	Maximum concurrent sessions allowed
`session_timeout`	integer	`3600`	Seconds of inactivity before a session is cleaned up
`job_retention_seconds`	integer	`86400`	Duration in seconds to keep completed job metadata (24 hours)

Environment Variable Overrides:

MATLAB_MCP_SESSIONS_MAX_SESSIONS
MATLAB_MCP_SESSIONS_SESSION_TIMEOUT
MATLAB_MCP_SESSIONS_JOB_RETENTION_SECONDS

sessions:
  max_sessions: 50
  session_timeout: 3600
  job_retention_seconds: 86400

Monitoring

Configures metrics collection, storage, and dashboard.

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable metrics collection and storage
`sample_interval`	integer	`10`	Seconds between metric samples
`retention_days`	integer	`7`	Days to retain historical metrics data
`db_path`	string	`"./monitoring/metrics.db"`	SQLite database path for metrics (resolved to absolute path at startup)
`dashboard_enabled`	boolean	`true`	Enable web dashboard for monitoring
`http_port`	integer	`8766`	HTTP port for dashboard and health endpoints (stdio transport only)

Environment Variable 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

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

pip install -e ".[monitoring]"
# or
pip install -e ".[dev]"  # dev includes all optional dependencies

monitoring:
  enabled: true
  sample_interval: 10
  retention_days: 7
  db_path: "./monitoring/metrics.db"
  dashboard_enabled: true
  http_port: 8766

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Configuration

Configuration

Config File Location

Environment Variable Overrides

Full Configuration Reference

Server

Pool

Execution

Workspace

Toolboxes

Custom Tools

Security

Code Checker

Output

Sessions

Monitoring

Example Configurations

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally