Skip to content

FAQ

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

FAQ

General / Overview

What is the MATLAB MCP Server?

The MATLAB MCP Server is a Python-based bridge that connects any MCP-compatible AI coding agent (Claude, Cursor, Copilot, etc.) to MATLAB for code execution. It exposes 20+ built-in tools for running MATLAB code, discovering toolboxes, managing async jobs, handling file operations, and monitoring server health.

See the Home page for a complete feature overview.

What MATLAB versions are supported?

MATLAB R2022b and later. The MATLAB Engine API for Python must be installed separately from your MATLAB installation. See Installation for setup instructions.

What's the license?

The project is open-source under the MIT License. See the repository for details.

Which AI agents are compatible?

Any agent supporting the Model Context Protocol (MCP):

  • Claude Desktop
  • Claude Code
  • Cursor
  • GitHub Copilot (with MCP support)
  • Custom agents built with MCP SDKs

See Agent-Onboarding for connection examples for each agent.

Can I use this without MATLAB installed?

No. The server requires a local MATLAB installation with the Engine API. It bridges to real MATLAB engines, not a simulator.

Can I run it in Docker?

Yes, but MATLAB is not included in the Docker image. You must mount your own MATLAB installation as a volume. See Installation for Docker setup.

Setup

How do I install the MATLAB Engine API?

The process varies by operating system:

macOS (Intel or Apple Silicon):

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 .

Replace R2024a with your installed MATLAB version. See Installation for full instructions.

What's the difference between stdio and SSE transports?

Transport Use Case Setup Sessions
stdio (default) Single agent, local Simple; no network 1 default session
SSE (deprecated) Multiple agents, remote HTTP server behind proxy Per-session isolation
Streamable HTTP Multiple agents, remote HTTP server (recommended) Per-session isolation

Recommendation: Use stdio for development/local testing. For production deployments with multiple agents, use streamable HTTP transport behind a reverse proxy with authentication.

See Configuration for transport setup details.

How do I set up bearer token authentication?

  1. Generate a token:
matlab-mcp --generate-token
  1. Set the environment variable:
export MATLAB_MCP_AUTH_TOKEN=<generated_token>
  1. When connecting agents, use the token in the Authorization header:
Authorization: Bearer <token>

The --generate-token flag prints shell-specific snippets for POSIX, Windows cmd, and PowerShell. No token configuration belongs in config.yaml — always use environment variables.

Can I run on Windows without administrator rights?

Yes. The server binds to 127.0.0.1 by default (localhost only), which does not require Windows Firewall elevation. See Windows-Deployment for a complete no-admin setup guide.

How do I deploy to a team?

See Windows-Deployment (for Windows 10 shared machines) and Agent-Onboarding (for connecting multiple agents). For production deployments, Security documents reverse-proxy and authentication best practices.

Performance

How much memory does the engine pool use?

Each MATLAB engine process consumes 500 MB–2 GB depending on loaded toolboxes. A pool of 4 engines typically uses 2–8 GB. Configure pool.min_engines and pool.max_engines based on available memory and concurrent user load.

How many engines should I run?

  • Personal use: 1–2 engines
  • Small team (2–5 concurrent users): 2–4 engines
  • Larger team: Scale based on concurrent usage and license limits

macOS: MATLAB limits you to approximately 4 concurrent engines due to OS constraints.

Can I scale horizontally (multiple servers)?

Yes. Set stateless_http: true in the server config. This disables session state so each request is self-contained — load balancers can route requests to any server instance without sticky sessions.

server:
  transport: streamablehttp
  stateless_http: true

What happens when all engines are busy?

Requests queue up (configurable sessions.queue_max_size, default 50). If the pool hasn't reached max_engines, a new engine starts automatically. Requests are served FIFO as engines become available.

How do I optimize execution time for long-running jobs?

Code exceeding execution.sync_timeout (30s default) automatically promotes to async execution. For code that typically takes 1–2 minutes:

execution:
  sync_timeout: 120  # Increase to 2 minutes

Use the mcp_progress() helper to report progress from long jobs:

mcp_progress(__mcp_job_id__, 50, 'Processing step 2 of 4');

See Async-Jobs for details.

Integration

How do I connect Claude Code?

See the "Claude Code" section in Agent-Onboarding. In brief:

  1. Ensure the server is running with --transport streamablehttp
  2. In Claude Code settings, add the MCP server configuration:
{
  "name": "matlab-mcp",
  "url": "http://localhost:8765/mcp",
  "auth": {
    "type": "bearer",
    "token": "${MATLAB_MCP_AUTH_TOKEN}"
  }
}
  1. Set the environment variable:
export MATLAB_MCP_AUTH_TOKEN=<your_token>

How do I connect Cursor?

See the "Cursor" section in Agent-Onboarding. Cursor supports both stdio (local) and HTTP (remote) configurations in .cursor/mcp_config.json:

{
  "mcpServers": {
    "matlab": {
      "command": "python",
      "args": ["-m", "matlab_mcp", "--transport", "stdio"],
      "env": {
        "MATLAB_MCP_AUTH_TOKEN": "<token>"
      }
    }
  }
}

How do I connect Codex CLI?

See the "Codex CLI" section in Agent-Onboarding. Codex CLI connects via HTTP with bearer token auth:

export MCP_SERVER_URL=http://localhost:8765/mcp
export MCP_AUTH_TOKEN=<your_token>
codex-cli --mcp-server $MCP_SERVER_URL --mcp-auth-header "Authorization: Bearer $MCP_AUTH_TOKEN"

How do I integrate with GitHub Actions or CI/CD?

The server supports environment variable overrides for all config values. Example GitHub Actions workflow:

- name: Run MATLAB via MCP
  env:
    MATLAB_MCP_AUTH_TOKEN: ${{ secrets.MATLAB_MCP_TOKEN }}
  run: |
    python -m matlab_mcp --transport stdio &
    # Agent connects and runs MATLAB code

Can I use custom MATLAB functions as tools?

Yes. Define them in a custom_tools.yaml file:

custom_tools:
  - name: signal_filter
    function: "signal_processing.filter_signal"
    parameters:
      input_file: {type: "string", description: "Input .wav file"}
      cutoff_hz: {type: "float", description: "Cutoff frequency"}
    returns: "Filtered signal and spectogram"

See Custom-Tools for full syntax and examples.

How do I set up monitoring and metrics?

Monitoring is enabled by default. Access the dashboard at:

http://localhost:8766/dashboard  (stdio transport)
http://localhost:8765/dashboard  (HTTP transport)

Customize with:

monitoring:
  enabled: true
  sample_interval: 10  # Seconds between samples
  retention_days: 7    # Keep 7 days of history
  dashboard_enabled: true

The dashboard shows real-time engine pool utilization, job throughput, execution time percentiles, error rates, and event logs. See Architecture for the monitoring stack.

Architecture & Internals

How does async job execution work?

By default, code runs synchronously and returns immediately. If execution exceeds execution.sync_timeout (30s default), the server automatically:

  1. Returns a job_id to the agent
  2. Continues running the code in the background
  3. Allows the agent to poll get_job_status(job_id) for progress
  4. Returns the full result via get_job_result(job_id) when complete

See Async-Jobs for examples and configuration.

How is the workspace isolated between sessions?

When execution.workspace_isolation: true (default), each session has a dedicated temp directory and workspace:

clear all
clear global
clear functions
fclose all
restoredefaultpath

This prevents state from leaking between users or agents.

What security measures are in place?

The server enforces:

  • Function blocklist: Blocks system(), eval(), unix(), dos(), ! and 7 other dangerous functions by default
  • Filename sanitization: Prevents path traversal in upload paths
  • Upload size limits: Configurable per-file size cap (default 100 MB)
  • Bearer token auth: On HTTP transports (stdio has no auth)
  • Session isolation: Workspaces cleared between sessions

See Security for the full security architecture.

How are MATLAB figures converted to interactive plots?

The server uses a three-stage pipeline:

  1. MATLAB-side (mcp_extract_props.m): Extracts figure properties (lines, surfaces, axes labels, colors)
  2. Python-side (plotly_style_mapper.py): Converts MATLAB styles to Plotly equivalents (line styles, markers, colormaps)
  3. Python-side (formatter.py): Builds a Plotly JSON response + static PNG

Agents receive interactive JSON suitable for web display + a PNG fallback.

See Architecture for the full data flow.

Troubleshooting

Server won't start — MATLAB Engine initialization hangs

This often happens on network-mapped drives. Add a timeout:

timeout 10 matlab-mcp --transport stdio

Or move the config and temp directories to a local drive.

Agent connection fails with HTTP 401

  1. Verify the auth token is set:
echo $MATLAB_MCP_AUTH_TOKEN

  1. For HTTP transports, ensure the Authorization: Bearer <token> header is present in agent config

  2. Check the server log:

matlab-mcp --log-level debug

Plots are blank or show as PNG fallback

This usually means the MATLAB figure conversion failed. Check:

  1. Is the code creating a figure without calling clf or close?
  2. Are all plot types supported? (Lines, scatter, bar, histogram, surface, image are fully supported; custom graphics may fall back to PNG)
  3. Check the server log for conversion errors

"Blocked function" error when code should be allowed

The security validator strips string literals and comments before scanning. If a false positive occurs:

  1. List currently blocked functions:
security:
  blocked_functions_enabled: true

  1. To disable a specific function from the blocklist, edit security.blocked_functions in config

  2. To disable all blocking temporarily:

export MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED=false

Async jobs stick in "RUNNING" status

This usually indicates the MATLAB engine crashed. Check:

  1. The server log for engine startup errors
  2. MATLAB for errors in the code itself
  3. Call cancel_job(job_id) to clean up stale jobs
  4. Restart the server to reset the engine pool

"Max sessions exceeded" error

The default limit is 10 concurrent sessions. Adjust in config:

sessions:
  max_sessions: 50  # Increase limit

See Configuration for other session tuning options.

Development

How do I run tests?

pip install -e ".[dev]"
pytest tests/ -v

Tests use a mock MATLAB engine — no real MATLAB installation required for testing.

How do I add a new MCP tool?

  1. Create the implementation in src/matlab_mcp/tools/
  2. Register it in server.py with the @mcp.tool() decorator
  3. Write tests in tests/test_tools_*.py
  4. Document it in MCP-Tools-Reference

How do I contribute?

  1. Fork the GitHub repository
  2. Create a feature branch
  3. Commit with conventional commit messages (feat:, fix:, docs:)
  4. Open a pull request

See CONTRIBUTING.md in the repository for detailed guidelines.

Clone this wiki locally