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

Note: Environment variable names are case-insensitive and automatically converted to lowercase. Type coercion is attempted in this order: int → float → bool → str. For example, MATLAB_MCP_EXECUTION_WORKSPACE_ISOLATION=true will be parsed as a boolean.

Limitation: Multi-word section names cannot be overridden via environment variables due to the underscore-based parsing convention. Use the config file for those sections instead.

Full Configuration Reference

Server

Field	Type	Default	Description
`name`	string	`"matlab-mcp-server"`	Server name reported to MCP clients
`transport`	`stdio` \| `sse`	`"stdio"`	Transport protocol for MCP communication
`host`	string	`"0.0.0.0"`	Bind address (SSE transport only)
`port`	integer	`8765`	Port number (SSE transport only)
`log_level`	`debug` \| `info` \| `warning` \| `error`	`"info"`	Logging verbosity level
`log_file`	string	`"./logs/server.log"`	Path to log file (resolved relative to config directory)
`result_dir`	string	`"./results"`	Directory for storing result files (resolved relative to config directory)
`drain_timeout_seconds`	integer	`300`	Max seconds to wait for running jobs during graceful shutdown

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

server:
  name: "matlab-mcp-server"
  transport: "stdio"                # stdio | sse
  host: "0.0.0.0"                   # only for SSE transport
  port: 8765                        # only for SSE transport
  log_level: "info"                 # debug | info | warning | error
  log_file: "./logs/server.log"
  result_dir: "./results"
  drain_timeout_seconds: 300

Pool

Field	Type	Default	Description
`min_engines`	integer	`2`	Minimum number of MATLAB engines to keep running
`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 engines
`engine_start_timeout`	integer	`120`	Seconds to wait for MATLAB engine to start
`health_check_interval`	integer	`60`	Seconds between engine health checks
`proactive_warmup_threshold`	float	`0.8`	Engine utilization ratio (0.0–1.0) to trigger proactive warmup
`queue_max_size`	integer	`50`	Maximum number of pending requests in queue
`matlab_root`	string \| null	`null`	Explicit MATLAB installation path; if `null`, 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

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                 # auto-detect, or set explicit path

macOS Note: MATLAB on macOS supports a maximum of 4 engine instances per Python process. The server will log a warning if max_engines > 4 on macOS but still respects the configured value. Stability issues may occur with more than 4 engines.

Execution

Field	Type	Default	Description
`sync_timeout`	integer	`30`	Seconds before auto-promoting synchronous execution to async job
`max_execution_time`	integer	`86400`	Hard time limit per job in seconds (86400 = 24 hours)
`workspace_isolation`	boolean	`true`	Clear workspace after each session ends
`engine_affinity`	boolean	`false`	Pin session to specific engine for workspace persistence across calls
`temp_dir`	string	`"./temp"`	Temporary file directory (resolved relative to config directory)
`temp_cleanup_on_disconnect`	boolean	`true`	Delete temporary files when session ends

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

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

sync_timeout: When code execution exceeds this timeout, the server automatically converts it to an async job and returns a job_id for polling. Increase this for workloads expected to take 30–60 seconds.

engine_affinity: When enabled, a session is pinned to a single engine, allowing workspace state (variables, functions) to persist across multiple calls. When disabled, each call may use a different engine with workspace isolation.

Workspace

Field	Type	Default	Description
`default_paths`	list of strings	`[]`	Paths automatically added to MATLAB path on engine start and workspace reset
`startup_commands`	list of strings	`["format long"]`	MATLAB commands executed on each engine start and after workspace reset

Environment overrides:

Multi-value sections cannot be overridden via environment variables; use the config file.

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

Toolboxes

Field	Type	Default	Description
`mode`	`whitelist` \| `blacklist` \| `all`	`"whitelist"`	Toolbox filtering mode
`list`	list of strings	See below	Toolbox names to include (whitelist) or exclude (blacklist)

Environment overrides:

MATLAB_MCP_TOOLBOXES_MODE
List items cannot be overridden via environment variables; use the config file.

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

Mode	Behavior
`whitelist`	Only toolboxes in `list` are reported to agents; others are hidden
`blacklist`	All installed toolboxes EXCEPT those in `list` are reported
`all`	All installed toolboxes are reported; `list` is ignored

Custom Tools

Field	Type	Default	Description
`config_file`	string	`"./custom_tools.yaml"`	Path to custom tools definition file (resolved relative to config directory)

Environment overrides:

MATLAB_MCP_CUSTOM_TOOLS_CONFIG_FILE

custom_tools:
  config_file: "./custom_tools.yaml"

See Custom Tools for the full custom tools format and examples.

Security

Field	Type	Default	Description
`blocked_functions_enabled`	boolean	`true`	Enable blocking of unsafe MATLAB functions
`blocked_functions`	list of strings	See below	MATLAB function names to block from execution
`max_upload_size_mb`	integer	`100`	Maximum file upload size in megabytes
`require_proxy_auth`	boolean	`false`	Set `true` if SSE is deployed behind an authentication proxy

Environment overrides:

MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED
MATLAB_MCP_SECURITY_MAX_UPLOAD_SIZE_MB
MATLAB_MCP_SECURITY_REQUIRE_PROXY_AUTH
List items cannot be overridden; use the config file.

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

blocked_functions: The security validator scans code for these function names. String literals and comments are stripped before scanning to avoid false positives. For example, disp('system') will not trigger a block.

Code Checker

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable code checking
`auto_check_before_execute`	boolean	`false`	Automatically run code checker before each 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
List items cannot be overridden; use the config file.

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

Output

Field	Type	Default	Description
`plotly_conversion`	boolean	`true`	Convert MATLAB figures to Plotly JSON format
`static_image_format`	`png` \| `jpg` \| `svg`	`"png"`	Image format for static figure exports
`static_image_dpi`	integer	`150`	DPI for static image exports
`thumbnail_enabled`	boolean	`true`	Generate thumbnails for large figures
`thumbnail_max_width`	integer	`400`	Maximum width in pixels for thumbnails
`large_result_threshold`	integer	`10000`	Number of elements above which tabular/matrix data is saved to file
`max_inline_text_length`	integer	`50000`	Character limit for inline text output before saving to file

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

output:
  plotly_conversion: true
  static_image_format: "png"        # png | jpg | svg
  static_image_dpi: 150
  thumbnail_enabled: true
  thumbnail_max_width: 400
  large_result_threshold: 10000     # elements — above this, save tabular/matrix data to file
  max_inline_text_length: 50000     # chars — above this, save text output to file

Sessions

Field	Type	Default	Description
`max_sessions`	integer	`50`	Maximum number of concurrent sessions
`session_timeout`	integer	`3600`	Seconds of inactivity before a session is automatically cleaned up (3600 = 1 hour)
`job_retention_seconds`	integer	`86400`	How long to retain completed job metadata (86400 = 24 hours)

Environment 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

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable metrics collection and monitoring
`sample_interval`	integer	`10`	Seconds between metric collection samples
`retention_days`	integer	`7`	Days to retain historical metrics
`db_path`	string	`"./monitoring/metrics.db"`	SQLite database file path (resolved relative to config directory)
`dashboard_enabled`	boolean	`true`	Enable web dashboard (stdio transport only)
`http_port`	integer	`8766`	Dashboard HTTP 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

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

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

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