Skip to content

Installation

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

Installation

Prerequisites

  • Python 3.10+ (3.12 recommended for best performance)
  • MATLAB R2022b+ installed locally
  • MATLAB Engine API for Python — included with MATLAB, requires separate installation

System Requirements

Platform MATLAB Versions Notes
macOS R2022b–R2024b Max 4 concurrent engines recommended (known stability limits)
Windows R2022b–R2024b Tested on Windows 10/11 with Python 3.10, 3.11, 3.12
Linux R2022b–R2024b Requires MATLAB license server or local installation

Installation Methods

Method 1: pip Install (Recommended)

Step 1: Install MATLAB Engine API for Python

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

macOS:

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

Windows (Command Prompt):

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

Linux:

cd /path/to/matlab/R2024a/extern/engines/python
pip install .

Adjust the path for your MATLAB version (e.g., R2023b, R2024a).

Verify the installation:

import matlab.engine
eng = matlab.engine.start_matlab()
result = eng.eval("2 + 2", nargout=1)
print(result)  # Should print 4.0
eng.quit()

Step 2: Install the MCP Server

pip install matlab-mcp-python

With optional dependencies:

# Install with monitoring dashboard and metrics
pip install "matlab-mcp-python[monitoring]"

# Install with development tools (testing, linting)
pip install "matlab-mcp-python[dev]"

# Install with everything
pip install "matlab-mcp-python[dev,monitoring]"

Step 3: Verify Installation

matlab-mcp --version

Expected output: matlab-mcp-server version 1.4.1

Method 2: Install from Source

Clone the Repository

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

Install MATLAB Engine API (same as Method 1, Step 1)

Install the Server in Development Mode

# Minimal install (no monitoring or dev tools)
pip install -e .

# With monitoring dashboard
pip install -e ".[monitoring]"

# With dev dependencies (pytest, ruff, etc.)
pip install -e ".[dev]"

# All extras
pip install -e ".[dev,monitoring]"

Verify Installation

# Run tests to verify everything works
pytest

# Check linting
ruff check src/

# Start the server
matlab-mcp

Method 3: Windows Installer (No pip Required)

A standalone Windows installer (install.bat) is provided for environments without pip or Python installed.

Requirements

  • Windows 10/11
  • MATLAB R2022b+ installed and in system PATH
  • Administrator access not required

Installation Steps

  1. Download install.bat from the repository

  2. Run the installer:

    install.bat

  3. Follow the prompts:

    • The script auto-detects Python 3.10+ or prompts you to install it
    • Auto-detects MATLAB installation or asks for the MATLAB root directory
    • Creates a virtual environment in matlab-mcp-env/
    • Installs all dependencies from bundled wheels (fully offline)

  4. Activate the virtual environment:

    matlab-mcp-env\Scripts\activate

  5. Verify installation:

    matlab-mcp --version

Troubleshooting the Windows Installer

"Python 3.10+ not found":

  • Install Python from python.org
  • Ensure you check "Add Python to PATH" during installation

"MATLAB not found":

  • Ensure MATLAB is in your system PATH: matlab -version
  • Or manually specify the MATLAB root when prompted

Wheels download fails:

  • The installer has a fallback to pip: if wheels are unavailable, it will use pip instead
  • Ensure you have internet access or use the offline wheels bundle

Method 4: Docker

Option A: Docker with docker-compose

  1. Edit docker-compose.yml to mount your MATLAB installation:

    volumes:
  - /path/to/MATLAB:/opt/matlab:ro

  2. Build and run:

    docker compose up

  3. Verify:

    curl http://localhost:8765/health
curl http://localhost:8766/health  # Dashboard

Option B: Manual Docker Build

  1. Build the image:

    docker build -t matlab-mcp .

  2. Run the container:

    docker run -p 8765:8765 -p 8766:8766 \
  -v /path/to/MATLAB:/opt/matlab:ro \
  -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab \
  matlab-mcp

Important: The Docker image does not include MATLAB. You must mount your local MATLAB installation. The image only includes Python and the MCP server code.

Docker Compose Configuration

version: '3.8'
services:
  matlab-mcp:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8765:8765"  # MCP/SSE transport
      - "8766:8766"  # Dashboard
    volumes:
      - ./config.yaml:/app/config.yaml
      - /path/to/MATLAB:/opt/matlab:ro
      - ./results:/app/results
      - ./monitoring:/app/monitoring
    environment:
      MATLAB_MCP_POOL_MATLAB_ROOT: /opt/matlab
      MATLAB_MCP_SERVER_TRANSPORT: sse
      MATLAB_MCP_POOL_MIN_ENGINES: 2
      MATLAB_MCP_POOL_MAX_ENGINES: 8

Virtual Environment Setup (Recommended)

# Create virtual environment
python3.10 -m venv .venv

# Activate (macOS/Linux)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Install MATLAB Engine API
cd /Applications/MATLAB_R2024a.app/extern/engines/python
pip install .

# Install the MCP server
cd /path/to/matlab-mcp-server-python
pip install -e ".[dev,monitoring]"

# Verify
pytest
matlab-mcp --help

Configuration

Quick Start

Minimal config (stdio mode, single user):

matlab-mcp  # Uses defaults

Multi-user config (SSE mode):

matlab-mcp --transport sse --config config_multiuser.yaml

Full config with all options:

matlab-mcp --config config.yaml --log-level debug

See Configuration Guide for all settings.

Connect to AI Agents

Claude Desktop

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

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

Then restart Claude.

Cursor

Add to .cursor/mcp.json:

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

Claude Code

claude mcp add matlab -- matlab-mcp

Multi-User (SSE Mode)

Start the server with SSE transport:

matlab-mcp --transport sse

Configure your client to connect to: http://localhost:8765/sse

Verification

1. Check Python & MATLAB Engine

import sys
print(f"Python {sys.version}")

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

eng = matlab.engine.start_matlab()
print(f"MATLAB version: {eng.version(nargout=1)}")
eng.quit()

2. Test the MCP Server

# Start server (stdio mode)
matlab-mcp &
SERVER_PID=$!

# Give it a moment to start
sleep 2

# Kill server
kill $SERVER_PID

3. Run the Test Suite

pytest -v --cov=src/matlab_mcp tests/

Expected: All tests pass with >90% coverage.

4. Health Check (SSE Mode)

# Terminal 1: Start server in SSE mode
matlab-mcp --transport sse &

# Terminal 2: Check health endpoint
curl http://localhost:8765/health

# Check metrics
curl http://localhost:8766/metrics

# Open dashboard
open http://localhost:8766/dashboard

Expected response (health endpoint):

{
  "status": "healthy",
  "uptime_seconds": 12.34,
  "engines": {"total": 2, "available": 2, "busy": 0},
  "jobs": {"active": 0, "completed": 0, "failed": 0},
  "sessions": {"active": 1}
}

Architecture Overview

graph TB
    Client["AI Agent<br/>(Claude, Cursor, etc.)"]
    Transport["Transport Layer<br/>(stdio / SSE)"]
    Server["MCP Server<br/>(FastMCP)"]
    Pool["Engine Pool Manager<br/>(2-10 engines)"]
    Executor["Job Executor<br/>(sync/async)"]
    Engine["MATLAB Engines<br/>(matlab.engine)"]
    Monitor["Monitoring<br/>(metrics, dashboard)"]
    
    Client -->|MCP Messages| Transport
    Transport --> Server
    Server --> Pool
    Server --> Executor
    Pool --> Engine
    Executor --> Engine
    Server --> Monitor
    Pool -.->|Pool Status| Monitor
    Executor -.->|Job Events| Monitor
    Monitor -->|HTTP| Client
    
    style Client fill:#e1f5ff
    style Server fill:#fff3e0
    style Pool fill:#f3e5f5
    style Engine fill:#e8f5e9
    style Monitor fill:#fce4ec
Loading

Troubleshooting Installation

MATLAB Engine API Not Found

# Verify MATLAB is installed
matlab -version

# Re-install Engine API
cd /Applications/MATLAB_R2024a.app/extern/engines/python
pip install --force-reinstall .

# Check installation
python -c "import matlab.engine; print('✓ MATLAB Engine API OK')"

Python Version Mismatch

The MATLAB Engine API must be installed with the same Python version that will run the MCP server.

# Check your Python version
python --version

# Check MATLAB Engine API compatibility
python -c "import matlab.engine; import sys; print(f'Python {sys.version_info.major}.{sys.version_info.minor}')"

"No module named 'matlab'"

  1. Ensure MATLAB Engine API is installed in your active Python environment
  2. If using a virtual environment, re-install the Engine API into that venv
  3. Check pip list | grep matlab

macOS: "matlab.engine not found"

On macOS, you may need to use python3 explicitly:

python3 --version  # Should be 3.10+
cd /Applications/MATLAB_R2024a.app/extern/engines/python
python3 -m pip install .

Windows: "MATLAB not in PATH"

Add MATLAB to your system PATH:

  1. Open Environment Variables (Windows key + "environment")
  2. Add: C:\Program Files\MATLAB\R2024a\bin to PATH
  3. Restart Command Prompt

Verify:

matlab -version

Engine Startup Timeout

If engines take >120 seconds to start:

  1. Check MATLAB startup time: matlab -r "quit" (should complete in <30s)
  2. Increase timeout in config: 
    pool:
  engine_start_timeout: 180  # 3 minutes

Docker: "MATLAB not found in container"

Ensure your MATLAB installation is mounted:

# Verify MATLAB is accessible inside container
docker run -v /path/to/MATLAB:/opt/matlab:ro matlab-mcp \
  bash -c "ls -la /opt/matlab/bin/matlab"

Next Steps

  1. Read the Configuration Guide to customize settings
  2. Check Examples for common MATLAB tasks
  3. Review Security for production deployments
  4. See MCP Tools Reference for available tools

Data Flow Diagram: Installation & Startup

sequenceDiagram
    participant User
    participant Installer
    participant Python
    participant MatlabEngine
    participant Pool
    participant Dashboard
    
    User->>Installer: Run install command
    Installer->>Python: Check version >= 3.10
    Python-->>Installer: OK (3.10+)
    Installer->>MatlabEngine: Verify installed
    MatlabEngine-->>Installer: OK
    Installer->>Pool: Create EnginePoolManager
    Pool->>MatlabEngine: Start min_engines (e.g., 2)
    MatlabEngine-->>Pool: Engines ready
    Installer->>Dashboard: Initialize (if enabled)
    Dashboard-->>Installer: Ready on :8766
    Installer-->>User: ✓ Server running on :8765
    
    User->>Python: Connect client
    Python->>Pool: Acquire engine
    Pool-->>Python: Engine allocated
    Python->>MatlabEngine: Execute code
    MatlabEngine-->>Python: Result
    Python-->>User: Return to agent
Loading

Clone this wiki locally