Installation

Prerequisites

System Requirements

Python 3.10+ (3.12 recommended for best performance)
MATLAB R2022b or later (R2024a or later recommended)
MATLAB Engine API for Python — included with MATLAB, requires separate installation into Python
Operating Systems: Linux, macOS (Intel/Apple Silicon), Windows 10+ (no admin required)

MATLAB Installation Verification

Verify your MATLAB installation:

# macOS/Linux
ls /opt/matlab/bin/matlab  # or /Applications/MATLAB_R*.app/bin/matlab
# Windows
where matlab.exe

Installation Methods

Method 1: PyPI (Recommended for Most Users)

The easiest installation path for Windows, macOS, and Linux.

Step 1: Create a Virtual Environment

python -m venv .venv
source .venv/bin/activate          # macOS/Linux
# or
.venv\Scripts\activate             # Windows

Step 2: Install MATLAB Engine API

The MATLAB Engine API must be installed into your Python environment first.

macOS:

cd /Applications/MATLAB_R2024a.app/extern/engines/python
pip install .

Replace R2024a with your MATLAB version (e.g., R2023b, R2024b).

Linux:

cd /opt/matlab/extern/engines/python
pip install .
# If MATLAB is in a non-standard location:
cd <MATLAB_ROOT>/extern/engines/python
pip install .

Windows:

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

Verify the installation:

import matlab.engine
print("MATLAB Engine API installed successfully")

Step 3: Install the MCP Server

pip install matlab-mcp-python

Optional: Install monitoring extras (for dashboard and health endpoints):

pip install 'matlab-mcp-python[monitoring]'

Optional: Install dev extras (for testing and development):

pip install 'matlab-mcp-python[dev]'

Step 4: Verify Installation

matlab-mcp --help

You should see the command-line options. Continue to #Verification Steps to test connectivity.

Method 2: Install from Source

For development, contributions, or custom configurations.

Step 1: Clone the Repository

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

Step 2: Create Virtual Environment and Install MATLAB Engine

python -m venv .venv
source .venv/bin/activate          # macOS/Linux
# or
.venv\Scripts\activate             # Windows

# Install MATLAB Engine API (see Method 1, Step 2 for platform-specific paths)
cd /Applications/MATLAB_R2024a.app/extern/engines/python
pip install .
cd /path/to/matlab-mcp-server-python

Step 3: Install in Development Mode

# Minimal installation (core only)
pip install -e .

# With monitoring support
pip install -e '.[monitoring]'

# With all dev and test dependencies
pip install -e '.[dev]'

Step 4: Run Tests

pytest tests/ -v

Expected: 750+ tests pass. If MATLAB is not available, mocked tests still run (marked with @pytest.mark.matlab are skipped).

Method 3: Windows Batch Installer (Windows 10+ Only)

A one-click installer for Windows users without admin rights.

Step 1: Download the Installer

Download install.bat from the project repository.

Step 2: Run the Installer

install.bat

The installer will:

Detect Python 3.10+ in your PATH
Locate MATLAB R2022b or later
Create a virtual environment
Install the MATLAB Engine API
Install matlab-mcp-python
Register with Windows Task Scheduler (optional)

Notes:

No administrator rights required
If MATLAB is not found, you can specify the path manually
The installer creates a .venv directory in the current folder

Method 4: Docker

For containerized deployments or CI/CD pipelines.

Prerequisites

Docker 20.10+
MATLAB installation available on the host (must be mounted into the container)

Step 1: Build the Docker Image

docker build -t matlab-mcp:latest .

Step 2: Run a Container

# Single instance with stdio transport
docker run -it --rm \
  -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab \
  matlab-mcp:latest

# Multi-user with streamable HTTP transport
docker run -d --rm \
  -p 8765:8765 \
  -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab \
  -e MATLAB_MCP_SERVER_TRANSPORT=streamablehttp \
  -e MATLAB_MCP_AUTH_TOKEN=$(python -c "import secrets; print(secrets.token_hex(32))") \
  matlab-mcp:latest

Step 3: Using Docker Compose

Edit docker-compose.yml to set your MATLAB path, then:

docker compose up

Important Notes on Docker:

graph LR
    A["Docker Container<br/>(matlab-mcp)"] -->|requires| B["MATLAB Installation<br/>(host mount)"]
    A -->|reads| C["MATLAB_MCP_POOL_MATLAB_ROOT<br/>environment variable"]
    B -->|mounted at| D["/opt/matlab"]
    C -->|points to| D

The Docker image does not include MATLAB. You must provide MATLAB via a host mount.
Set MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab (or your mount path) as an environment variable.
For remote connections, use streamablehttp transport with bearer token authentication (see #Authentication Setup below).

Example with authentication:

export MATLAB_MCP_AUTH_TOKEN=$(python -c "import secrets; print(secrets.token_hex(32))")

docker run -d \
  -p 8765:8765 \
  -v /opt/MATLAB/R2024a:/opt/matlab:ro \
  -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab \
  -e MATLAB_MCP_SERVER_TRANSPORT=streamablehttp \
  -e MATLAB_MCP_AUTH_TOKEN=$MATLAB_MCP_AUTH_TOKEN \
  matlab-mcp:latest

Transport Configuration

The server supports three transport modes:

graph TB
    subgraph Transports
        A["stdio<br/>(Default)"]
        B["sse<br/>(Deprecated)"]
        C["streamablehttp<br/>(Recommended)"]
    end
    subgraph Use_Case
        A --> A1["Single local agent"]
        B --> B1["Multiple remote agents<br/>Legacy support"]
        C --> C1["Multiple agents<br/>Load-balanced setup"]
    end

stdio (Default — Single User, Local)

Best for local development and single-user deployments.

matlab-mcp --transport stdio

No network overhead
Simple setup (no config needed)
Single agent per instance
Used by Claude Desktop, Cursor, local testing

streamablehttp (Recommended — Multi-User, Remote)

Best for team deployments and remote agents like Codex CLI.

matlab-mcp --transport streamablehttp --host 127.0.0.1 --port 8765

Configuration in config.yaml:

server:
  transport: streamablehttp
  host: 127.0.0.1          # Loopback for no-admin on Windows; change to 0.0.0.0 for network access
  port: 8765
  
sessions:
  max_sessions: 10         # Limit concurrent agents
  session_timeout: 3600    # Auto-cleanup after 1 hour idle

Multiple concurrent agents
HTTP/WebSocket-based
Requires authentication (see #Authentication Setup)
Agents connect to http://localhost:8765/mcp
Stateless mode available for load balancing (stateless_http: true)

sse (Deprecated — Legacy Support Only)

Server-Sent Events transport (kept for backward compatibility).

matlab-mcp --transport sse --host 0.0.0.0 --port 8765

Status: Deprecated as of v2.0. Use streamablehttp for new deployments. Existing SSE clients continue to work with a deprecation warning logged at startup.

Authentication Setup

Authentication is required for streamablehttp transport. Bearer tokens sourced from environment variables only (not config files).

Step 1: Generate an Authentication Token

matlab-mcp --generate-token

Output example:

Generated bearer token: a3f7c2e9d1b5a8f4c6e2d9b1a3f5c7e9

# macOS/Linux: Add to your shell profile
export MATLAB_MCP_AUTH_TOKEN="a3f7c2e9d1b5a8f4c6e2d9b1a3f5c7e9"

# Windows Command Prompt
set MATLAB_MCP_AUTH_TOKEN=a3f7c2e9d1b5a8f4c6e2d9b1a3f5c7e9

# Windows PowerShell
$env:MATLAB_MCP_AUTH_TOKEN = "a3f7c2e9d1b5a8f4c6e2d9b1a3f5c7e9"

Step 2: Set the Environment Variable

macOS/Linux:

export MATLAB_MCP_AUTH_TOKEN="a3f7c2e9d1b5a8f4c6e2d9b1a3f5c7e9"

Or add to ~/.bashrc or ~/.zshrc for persistence:

echo 'export MATLAB_MCP_AUTH_TOKEN="a3f7c2e9d1b5a8f4c6e2d9b1a3f5c7e9"' >> ~/.bashrc
source ~/.bashrc

Windows Command Prompt:

set MATLAB_MCP_AUTH_TOKEN=a3f7c2e9d1b5a8f4c6e2d9b1a3f5c7e9

To persist, use:

setx MATLAB_MCP_AUTH_TOKEN "a3f7c2e9d1b5a8f4c6e2d9b1a3f5c7e9"

Windows PowerShell:

$env:MATLAB_MCP_AUTH_TOKEN = "a3f7c2e9d1b5a8f4c6e2d9b1a3f5c7e9"

To persist:

[Environment]::SetEnvironmentVariable("MATLAB_MCP_AUTH_TOKEN", "a3f7c2e9d1b5a8f4c6e2d9b1a3f5c7e9", "User")

Step 3: Start the Server

# Token is automatically read from MATLAB_MCP_AUTH_TOKEN
matlab-mcp --transport streamablehttp

Expected output:

Starting MATLAB MCP Server v1.5.0...
[INFO] Loaded MATLAB Engine API
[INFO] Pool: 2 min, 10 max engines
[WARNING] Bearer token authentication enabled
[INFO] HTTP endpoint: http://127.0.0.1:8765/mcp
[INFO] Dashboard: http://127.0.0.1:8765/dashboard

Authentication in Agents

See Agent-Onboarding for connection examples with bearer token headers for Claude Code, Codex CLI, and Cursor.

Verification Steps

1. Test Basic Functionality (stdio)

matlab-mcp --transport stdio

In another terminal:

import json
import subprocess

# Start server (if not already running)
proc = subprocess.Popen(['matlab-mcp', '--transport', 'stdio'],
                       stdin=subprocess.PIPE,
                       stdout=subprocess.PIPE,
                       stderr=subprocess.PIPE,
                       text=True)

# Send MCP initialize request
request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
        "protocolVersion": "2024-11-05",
        "capabilities": {},
        "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
}

proc.stdin.write(json.dumps(request) + '\n')
proc.stdin.flush()

# Read response (first line)
response = json.loads(proc.stdout.readline())
assert response['result']['protocolVersion'] == "2024-11-05"
assert 'tools' in response['result']

print("✓ Server initialized successfully")
print(f"✓ Available tools: {len(response['result']['tools'])}")

proc.terminate()

Expected output:

✓ Server initialized successfully
✓ Available tools: 20

2. Test HTTP/streamablehttp Transport

# Terminal 1: Start server
export MATLAB_MCP_AUTH_TOKEN="your-token-here"
matlab-mcp --transport streamablehttp --host 127.0.0.1 --port 8765

# Terminal 2: Test health endpoint
curl -H "Authorization: Bearer your-token-here" \
     http://127.0.0.1:8765/health

# Expected response:
# {"status": "healthy", "uptime": 0.5, ...}

3. Test Tool Registration

# Check that tools are registered
curl -H "Authorization: Bearer your-token-here" \
     http://127.0.0.1:8765/mcp/tools

# Expected: JSON with 20+ tools including execute_code, get_workspace, list_toolboxes

4. Test Dashboard Access

Open in browser: http://127.0.0.1:8765/dashboard (authentication not required for dashboard)

Expected: Real-time metrics with pool utilization, active jobs, session counts.

5. Run Full Test Suite

pytest tests/ -v --tb=short

Expected: 750+ tests pass.

If MATLAB Engine is not available, ~150 tests are skipped (marked @pytest.mark.matlab), but mocked tests still run.

Platform-Specific Notes

macOS

Engine Limit:

MATLAB on macOS has a hard limit of 4 concurrent engines. The server will log a warning if configured higher:

[WARNING] Pool max_engines=8 exceeds macOS limit of 4. Capping to 4.

Solution: Set max_engines: 4 in config.yaml for macOS deployments.

Apple Silicon (M1/M2/M3):

MATLAB R2023b and later have native ARM64 support. Earlier versions use Rosetta translation. Verify:

matlab -nojvm -batch "arch"
# Output: arm64 (native) or x86_64 (translated)

Windows 10/11

No Admin Required:

The server defaults to host: 127.0.0.1 (loopback only) to avoid Windows Firewall prompts. No elevated permissions are needed.

Firewall Access:

If you need remote access, change host: 0.0.0.0 in config.yaml. Windows Firewall will prompt once on first run; allow Python through.

Virtual Environments:

Always use a virtual environment on Windows:

python -m venv .venv
.venv\Scripts\activate
pip install matlab-mcp-python

Linux

MATLAB Path:

If MATLAB is installed to a non-standard location, set:

export MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab/R2024a
matlab-mcp

Or in config.yaml:

pool:
  matlab_root: /opt/matlab/R2024a

Ubuntu/Debian Specifics:

Install MATLAB Engine API dependencies:

sudo apt-get install python3-dev

Troubleshooting Installation

"ModuleNotFoundError: No module named 'matlab'"

Problem: MATLAB Engine API not installed.

Solution:

cd /Applications/MATLAB_R2024a.app/extern/engines/python
pip install .

Verify:

import matlab.engine
print("OK")

"MATLAB not found on PATH"

Problem: MATLAB executable not in system PATH.

Solution: Explicitly set the MATLAB root:

export MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab/R2024a  # Linux
export MATLAB_MCP_POOL_MATLAB_ROOT=/Applications/MATLAB_R2024a.app  # macOS
set MATLAB_MCP_POOL_MATLAB_ROOT=C:\Program Files\MATLAB\R2024a  # Windows

matlab-mcp

"ConnectionRefusedError: [Errno 111] Connection refused"

Problem: Server failed to bind to port 8765.

Causes:

Port already in use
Firewall blocking (Windows)
Insufficient permissions for port <1024 (Linux)

Solution:

# Find what's using port 8765
lsof -i :8765  # macOS/Linux
netstat -ano | findstr :8765  # Windows

# Use a different port
matlab-mcp --port 9000

"MATLAB startup timeout (120 seconds exceeded)"

Problem: MATLAB Engine taking too long to start.

Causes:

Network drive access (MATLAB on mounted paths)
Slow system or high load
First-time MATLAB activation

Solution:

# Increase timeout in config.yaml
pool:
  engine_start_timeout: 300  # 5 minutes instead of default 2 minutes

pytest: "RuntimeError: no running event loop"

Problem: Tests fail with async/await issues.

Solution: Ensure pytest-asyncio is installed:

pip install pytest-asyncio
python -m pytest tests/ -v

Next Steps

Quick Start: Run matlab-mcp and connect your agent (see Agent-Onboarding)
Configuration: Customize pool size, timeout, and paths (see Configuration)
Monitoring: Enable the dashboard for real-time metrics (see Configuration#Monitoring)
Custom Tools: Expose your own MATLAB functions (see Custom-Tools)

Installation

Installation

Prerequisites

System Requirements

MATLAB Installation Verification

Installation Methods

Method 1: PyPI (Recommended for Most Users)

Step 1: Create a Virtual Environment

Step 2: Install MATLAB Engine API

Step 3: Install the MCP Server

Step 4: Verify Installation

Method 2: Install from Source

Step 1: Clone the Repository

Step 2: Create Virtual Environment and Install MATLAB Engine

Step 3: Install in Development Mode

Step 4: Run Tests

Method 3: Windows Batch Installer (Windows 10+ Only)

Step 1: Download the Installer

Step 2: Run the Installer

Method 4: Docker

Prerequisites

Step 1: Build the Docker Image

Step 2: Run a Container

Step 3: Using Docker Compose

Transport Configuration

stdio (Default — Single User, Local)

streamablehttp (Recommended — Multi-User, Remote)

sse (Deprecated — Legacy Support Only)

Authentication Setup

Step 1: Generate an Authentication Token

Step 2: Set the Environment Variable

Step 3: Start the Server

Authentication in Agents

Verification Steps

1. Test Basic Functionality (stdio)

2. Test HTTP/streamablehttp Transport

3. Test Tool Registration

4. Test Dashboard Access

5. Run Full Test Suite

Platform-Specific Notes

macOS

Windows 10/11

Linux

Troubleshooting Installation

"ModuleNotFoundError: No module named 'matlab'"

"MATLAB not found on PATH"

"ConnectionRefusedError: [Errno 111] Connection refused"

"MATLAB startup timeout (120 seconds exceeded)"

pytest: "RuntimeError: no running event loop"

Next Steps

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