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 MCP (Model Context Protocol) bridge that connects AI coding agents (Claude, Cursor, Copilot, etc.) to MATLAB. It enables agents to execute MATLAB code, discover toolboxes, manage files, inspect workspaces, and view interactive Plotly plots — all through a standard MCP interface.

**Architecture:** The server manages an elastic pool of MATLAB engines, routes requests per-session with workspace isolation, enforces security policies (blocked functions, file upload limits), collects metrics, and supports both local (stdio) and remote (HTTP/streamable) transports.

See [[Architecture]] for a detailed system overview.

### What MATLAB versions are supported?

**MATLAB R2022b and later.** The MATLAB Engine API for Python must be installed separately from your MATLAB installation.

```bash
# Example: macOS
cd /Applications/MATLAB_R2024a.app/extern/engines/python
pip install .

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

What Python versions are required?

Python 3.10, 3.11, or 3.12. The project uses modern async/await patterns and requires pydantic>=2.0 for configuration validation.

What is the license?

MIT License. See LICENSE in the repository.

What AI agents are supported?

Any agent that implements the Model Context Protocol:

  • Claude Desktop — via MCP configuration in claude_desktop_config.json
  • Claude Code — native MCP integration with claude mcp add
  • Cursor — MCP settings in .cursor/settings.json
  • Codex CLI — supports both stdio and streamable HTTP transports
  • Custom agents built with MCP SDKs (Python, JavaScript, Rust, Go)

See Agent-Onboarding for connection examples for each agent.

Setup

How do I install it?

Option 1: PyPI (recommended)

pip install matlab-mcp-python
matlab-mcp  # Run it

Option 2: Windows one-click installer (no admin rights)

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

Option 3: Source installation

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

Option 4: Conda

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

See Installation for detailed platform-specific instructions.

What's the minimum viable setup?

  1. Install MATLAB R2022b+ with Engine API
  2. pip install matlab-mcp-python
  3. matlab-mcp (stdio transport, single user, no auth)

That's it. No config files required for basic use.

How do I connect Claude Desktop?

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp"
    }
  }
}

Restart Claude Desktop. The MATLAB tools appear in the "Composer" panel.

How do I set up bearer token authentication?

  1. Generate a token:

    matlab-mcp --generate-token

  2. Export the environment variable (shown by the command):

    export MATLAB_MCP_AUTH_TOKEN=<64-char-hex-token>

  3. Start the server with HTTP transport:

    matlab-mcp --transport http

  4. Configure your agent to send the bearer token (see Agent-Onboarding).

See Configuration for advanced auth setup.

Can I run it in Docker?

Yes. The repository includes docker-compose.test.yml (for remote integration testing). For production, create a docker-compose.yml that mounts your MATLAB installation:

version: '3.8'
services:
  matlab-mcp:
    build: .
    ports:
      - "8765:8765"
    environment:
      - MATLAB_MCP_AUTH_TOKEN=${AUTH_TOKEN}
    volumes:
      - /opt/matlab:/opt/matlab  # Mount your MATLAB installation

See Installation for Docker setup.

stdio vs streamable HTTP vs SSE — which should I use?

graph TD
    A["Transport Choice"]
    A -->|Single user, local| B["stdio"]
    A -->|Multi-user, remote| C["HTTP/Streamable"]
    A -->|Deprecated| D["SSE"]
    
    B --> B1["No auth, no config, simplest"]
    C --> C1["Bearer token auth, configurable"]
    D --> D1["Legacy, use streamable instead"]
Loading
Transport Single/Multi-User Auth Config When to Use
stdio Single None No Local development, Claude Desktop
streamable HTTP Multi Bearer token Yes Remote agents, Codex CLI, production
SSE Multi Proxy auth only Yes Deprecated (use streamable instead)

See Configuration for transport setup.

Performance

How many MATLAB engines should I run?

The pool auto-scales between min_engines (default: 2) and max_engines (default: 10).

Scenario Recommended
Personal use, one agent 1-2
Small team (2-5 concurrent users) 2-4
Medium team (5-10 concurrent users) 4-8
Large team or long simulations 8-16

Check your MATLAB license limits. On macOS, MATLAB limits you to ~4 concurrent engines regardless of configuration.

Configure via config.yaml:

pool:
  min_engines: 2
  max_engines: 16

Or environment variable:

export MATLAB_MCP_POOL_MAX_ENGINES=16
matlab-mcp

How much memory does each engine use?

Typically 500MB to 2GB per engine, depending on:

  • MATLAB version
  • Loaded toolboxes
  • Workspace variables
  • Active jobs

For a team of 5 with 4 engines, budget 2-8GB of RAM.

What's the difference between sync and async execution?

graph TD
    A["Code Submitted"]
    A --> B{Finishes within<br/>sync_timeout?}
    B -->|Yes (< 30s)| C["Return result immediately"]
    B -->|No (> 30s)| D["Create job, return job_id"]
    D --> E["Agent polls progress<br/>via get_job_status"]
    E --> F["Eventually get result<br/>via get_job_result"]
Loading
  • Sync: Fast commands (< 30 seconds) return immediately with results
  • Async: Slow jobs return a job_id and run in the background; agent polls for progress

Default sync_timeout: 30 seconds. Configure in config.yaml or via MATLAB_MCP_EXECUTION_SYNC_TIMEOUT_SECONDS.

See Async-Jobs for examples.

How do I optimize for large simulations?

  1. Increase sync_timeout for long-running code:

    export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT_SECONDS=300

  2. Add progress reporting via mcp_progress() in your MATLAB code:

    for i = 1:1000
    % ... computation ...
    if mod(i, 100) == 0
        mcp_progress(__mcp_job_id__, i/10, sprintf('Iteration %d', i));
    end
end

  3. Increase engine pool to handle multiple concurrent simulations:

    export MATLAB_MCP_POOL_MAX_ENGINES=16

See Async-Jobs and Examples for code patterns.

What happens when all engines are busy?

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

Queue status is visible in the monitoring dashboard (/dashboard).

Integration

How do I integrate with GitHub Actions?

Example: Run MATLAB code as part of your CI pipeline

name: MATLAB Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.10'
      
      - name: Install MATLAB Engine API
        run: |
          cd /opt/matlab/extern/engines/python
          pip install .
      
      - name: Install MCP server
        run: pip install matlab-mcp-python
      
      - name: Run MATLAB tests
        run: |
          matlab-mcp --inspect &
          sleep 2
          python -c "from matlab_mcp.tools.core import execute_code_impl; ..."

See tests/test_mcp_integration.py in the repo for an end-to-end CI example.

How do I expose it safely over the network?

Do not expose the raw HTTP endpoint directly. Always use a reverse proxy with authentication:

upstream matlab_mcp {
    server 127.0.0.1:8765;
}

server {
    listen 443 ssl;
    server_name matlab-mcp.example.com;

    location /mcp {
        auth_basic "MATLAB MCP Server";
        auth_basic_user_file /etc/nginx/.htpasswd;
        
        proxy_pass http://matlab_mcp;
        proxy_read_timeout 60s;
    }
}

Configure the server to accept proxy auth:

security:
  require_proxy_auth: true

See Security for detailed hardening guidance.

How do I use custom MATLAB functions as MCP tools?

Define them in a custom_tools.yaml file:

custom_tools:
  - name: signal_analysis
    description: Analyze frequency content of a signal
    function: my_toolbox.signal_analysis
    parameters:
      signal:
        type: ndarray
        description: Input signal vector
      fs:
        type: number
        description: Sampling frequency
    returns:
      freqs: Frequency vector
      magnitudes: FFT magnitudes

Load it with:

export MATLAB_MCP_CUSTOM_TOOLS_FILE=/path/to/custom_tools.yaml
matlab-mcp

See Custom-Tools for detailed examples.

How do I integrate with CI/CD pipelines?

Use the --inspect flag to run without MATLAB (dry-run mode):

matlab-mcp --inspect --transport http --port 8765 &

Then connect a real MCP client to http://127.0.0.1:8765/mcp to verify the server starts and tools are registered. See tests/test_mcp_integration.py for a real example.

Does it work with Docker and Kubernetes?

Docker: Yes, with mounted MATLAB installation (see Installation).

Kubernetes: Possible but complex — MATLAB licensing is per-machine, not per-container. Consider:

  • StatefulSet with a persistent MATLAB license
  • Host mount of MATLAB installation
  • Session affinity to ensure requests return to the same pod
  • Monitoring to detect dead pods

See Windows-Deployment for a Windows container example.

How do I monitor the server in production?

The server exposes a monitoring dashboard at /dashboard (when monitoring is enabled):

matlab-mcp --monitoring-enabled &
# Open http://127.0.0.1:8766/dashboard

Or query metrics programmatically:

curl http://127.0.0.1:8766/metrics
# Returns JSON with pool utilization, active jobs, error rates, etc.

Enable metrics persistence:

monitoring:
  enabled: true
  metrics_store_path: /var/log/matlab_mcp/metrics.db
  sampling_interval_seconds: 10

See Configuration for monitoring options.

Troubleshooting

"MATLAB engine failed to start"

Cause: MATLAB Engine API not installed or Python version mismatch.

Fix:

# Reinstall Engine API for your Python version
cd /Applications/MATLAB_R2024a.app/extern/engines/python  # macOS
python --version  # Verify Python 3.10-3.12
pip install .

"Connection refused" when connecting from remote agent

Cause: Server bound to 127.0.0.1 (loopback only) but accessed from another machine.

Fix: Bind to 0.0.0.0:

matlab-mcp --host 0.0.0.0

Warning (Windows): Binding to 0.0.0.0 triggers Windows Firewall, which may prompt for admin rights. Use a reverse proxy on the same machine instead.

See Windows-Deployment for details.

"Bearer token not accepted"

Cause: Mismatch between server token and agent token.

Fix:

# 1. Generate a new token
matlab-mcp --generate-token
# Output: MATLAB_MCP_AUTH_TOKEN=abc123def456...

# 2. Set it and restart the server
export MATLAB_MCP_AUTH_TOKEN=abc123def456...
matlab-mcp --transport http

# 3. Configure agent with exact same token

See Agent-Onboarding for agent-specific examples.

"Blocked function: system()"

Cause: Security validator blocked a potentially dangerous function.

Fix: Either use a MATLAB alternative or customize the blocklist:

security:
  blocked_functions:
    - system
    - unix
    # Remove entries to allow them

See Security for the default blocklist and safe alternatives.

"Plot conversion failed"

Cause: Complex custom graphics or unsupported plot type.

Fix: The server automatically generates a static PNG fallback. For interactive plots, stick to standard MATLAB plot types (line, scatter, bar, surface, histogram).

See Examples for supported plot examples.

Memory leak / server slows down over time

Cause: Job tracker not pruned, metrics store growing unbounded.

Fix:

jobs:
  retention_hours: 24  # Prune jobs older than 24 hours
monitoring:
  metrics_retention_hours: 168  # Prune metrics older than 7 days

Or restart the server periodically in production (e.g., via systemd timer).

FAQ

How do I report a bug?

Open an issue on GitHub with:

  • MATLAB version (version command)
  • Python version (python --version)
  • Transport used (stdio/HTTP/SSE)
  • Full error message and stack trace

How do I contribute?

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Write tests (pytest)
  4. Submit a pull request

See Architecture and Testing in the wiki for development guidelines.

Why SSE is deprecated in favor of streamable HTTP?

SSE (Server-Sent Events) is a one-way streaming protocol. It requires a persistent connection and doesn't handle errors gracefully. Streamable HTTP (MCP's HTTP transport in FastMCP 3.0+) is:

  • Bidirectional (requests/responses)
  • Stateless (better for load-balancing)
  • Standard HTTP (proxy-compatible)
  • Officially recommended by MCP spec

All production deployments should use streamablehttp transport.

Can I use the server with MATLAB Parallel Computing Toolbox?

Yes, but each MATLAB engine is a separate process. If your code uses parpool() inside one engine, that's within that engine's workspace — it doesn't distribute across the engine pool. For cluster computing, consider:

  • Running long jobs async (sync_timeout setting)
  • Using parpool within a single large engine
  • Custom tools that batch jobs across multiple independent MATLAB calls

Why is this better than just using matlab -batch?

graph TD
    A["MATLAB Code Execution"]
    A -->|matlab -batch| B["Single process, slow startup, no connection pooling"]
    A -->|MATLAB Engine API| C["This server: persistent engines, instant execution, session isolation"]
Loading

This server:

  • Keeps MATLAB engines warm (no 5-10s startup per command)
  • Shares a pool across multiple agents
  • Maintains per-session workspaces
  • Supports async jobs, progress reporting, interactive plots
  • Provides HTTP access for remote agents

Further Reading

Clone this wiki locally