Installation

Prerequisites

Python 3.10–3.12
MATLAB 2020b+ installed locally
MATLAB Engine API for Python — comes with MATLAB, requires separate installation

System Requirements

OS	Status	Notes
macOS (Intel/Apple Silicon)	✅ Supported	See macOS notes below
Windows 10/11	✅ Supported	Use `install.bat` for offline setup
Linux	⚠️ Limited	MATLAB Engine API support varies; may require manual setup

macOS Specifics

Apple Silicon: Use MATLAB R2023b or later for native support
Engine limits: Each MATLAB process uses significant memory. Start with min_engines: 1–2
Path detection: The installer auto-detects MATLAB in /Applications/MATLAB_*.app/

Windows Specifics

Offline setup: Run install.bat to download wheels and install without internet
Virtual environment: Recommended to avoid system-wide Python pollution
Admin rights: Not required; installation is user-scoped

Installation Methods

graph TD
    A["Choose Installation Method"] --> B{Transport Type?}
    B -->|Local / Single User| C["Option 1: PyPI + stdio"]
    B -->|Remote / Multi-User| D["Option 2: Source + SSE"]
    B -->|Offline / Windows| E["Option 3: install.bat"]
    B -->|Containerized| F["Option 4: Docker"]
    
    C --> C1["pip install matlab-mcp-python<br/>matlab-mcp"]
    D --> D1["git clone + pip install -e .<br/>matlab-mcp --transport sse"]
    E --> E1["install.bat<br/>matlab-mcp"]
    F --> F1["docker build + docker run<br/>or docker compose up"]
    
    C1 --> Z["✅ Ready to use"]
    D1 --> Z
    E1 --> Z
    F1 --> Z

Method 1: Install from PyPI (Recommended)

Best for local single-user setups.

Step 1a: Install MATLAB Engine API

The MATLAB Engine API lets Python call MATLAB. It comes with your MATLAB installation.

macOS

# Find your MATLAB installation (adjust version as needed)
cd /Applications/MATLAB_R2024a.app/extern/engines/python

# Create a virtual environment (optional but recommended)
python3 -m venv ~/.matlab-mcp-venv
source ~/.matlab-mcp-venv/bin/activate

# Install the MATLAB Engine API
pip install .

Note: Adjust the path for your MATLAB version (R2023b, R2024b, etc.).

Windows

REM Open Command Prompt or PowerShell

REM Adjust version as needed (e.g., R2023b, R2024b)
cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"

REM Create a virtual environment (optional but recommended)
python -m venv %USERPROFILE%\.matlab-mcp-venv
%USERPROFILE%\.matlab-mcp-venv\Scripts\activate

REM Install the MATLAB Engine API
pip install .

Verify MATLAB Engine Installation

import matlab.engine

# Start an engine and test it
eng = matlab.engine.start_matlab()
result = eng.eval("2 + 2", nargout=1)
print(result)  # Should print 4.0
eng.quit()

Step 1b: Install the MCP Server

# Activate your virtual environment if you created one
# source ~/.matlab-mcp-venv/bin/activate  # macOS
# %USERPROFILE%\.matlab-mcp-venv\Scripts\activate  # Windows

# Install from PyPI
pip install matlab-mcp-python

Step 1c: Verify Installation

# Check that the CLI is available
matlab-mcp --help

# Output should show:
# usage: matlab-mcp [-h] [--config CONFIG] [--transport {stdio,sse}]
#                   [--log-level {DEBUG,INFO,WARNING,ERROR}]

Method 2: Install from Source

Best for development, multi-user deployments, or if you want to customize.

Step 2a: Clone the Repository

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

Step 2b: Create a Virtual Environment

# macOS/Linux
python3 -m venv .venv
source .venv/bin/activate

# Windows
python -m venv .venv
.venv\Scripts\activate

Step 2c: Install MATLAB Engine API (if not already done)

cd /Applications/MATLAB_R2024a.app/extern/engines/python  # macOS
# or
cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"  # Windows

pip install .

# Return to the repo directory
cd /path/to/matlab-mcp-server-python

Step 2d: Install the Server with Dependencies

# Development setup (includes testing, linting, monitoring)
pip install -e ".[dev]"

# Or minimal setup (code execution only)
pip install -e .

# Or monitoring-only (add dashboard, health checks)
pip install -e ".[monitoring]"

Step 2e: Verify Installation

python -m matlab_mcp.server --help
# or
matlab-mcp --help

Method 3: Offline Installation (Windows Batch Script)

Best for Windows systems without reliable internet or for reproducible deployments.

Step 3a: Run the Offline Installer

REM Navigate to the repo
cd matlab-mcp-server-python

REM Run the installer batch script
install.bat

What install.bat does:

Detects Python 3.10–3.12 on your system
Creates a virtual environment in .venv
Downloads pre-built wheels (from requirements-lock.txt) into a vendor/ directory
Installs the server and MATLAB Engine API from local wheels (no internet required)

Output:

[✓] Python 3.11 detected
[✓] Virtual environment created at .venv\
[✓] Downloaded 45 wheels to vendor/
[✓] matlab-mcp-python installed successfully
[✓] Ready to use: matlab-mcp

Step 3b: Activate and Use

.venv\Scripts\activate
matlab-mcp

Method 4: Docker

Best for containerized, cloud, or reproducible deployments.

Step 4a: Build the Docker Image

cd matlab-mcp-server-python

# Build the image (this may take a few minutes)
docker build -t matlab-mcp:latest .

Step 4b: Run with Your MATLAB Installation

Docker doesn't include MATLAB. You must mount your local MATLAB installation:

# Run the container with MATLAB mounted
docker run \
  --name matlab-mcp \
  -p 8765:8765 \
  -p 8766:8766 \
  -v /Applications/MATLAB_R2024a.app:/opt/matlab:ro \
  -v /path/to/config.yaml:/app/config.yaml:ro \
  -v /tmp/matlab-mcp-results:/tmp/matlab-mcp-results \
  matlab-mcp:latest

# macOS example:
docker run \
  --name matlab-mcp \
  -p 8765:8765 \
  -p 8766:8766 \
  -v /Applications/MATLAB_R2024a.app:/opt/matlab:ro \
  matlab-mcp:latest

# Windows (PowerShell):
docker run `
  --name matlab-mcp `
  -p 8765:8765 `
  -p 8766:8766 `
  -v "C:\Program Files\MATLAB\R2024a":"C:\matlab":ro `
  matlab-mcp:latest

Step 4c: Using Docker Compose

Edit docker-compose.yml to point to your MATLAB installation:

services:
  matlab-mcp:
    image: matlab-mcp:latest
    ports:
      - "8765:8765"
      - "8766:8766"
    volumes:
      - /Applications/MATLAB_R2024a.app:/opt/matlab:ro
      - ./config.yaml:/app/config.yaml:ro
    environment:
      MATLAB_MCP_POOL_MATLAB_ROOT: /opt/matlab

Then start it:

docker compose up -d

# View logs
docker compose logs -f matlab-mcp

# Stop
docker compose down

Step 4d: Verify Docker Container

# Check if the server is responding
curl http://localhost:8765/health

# View logs
docker logs matlab-mcp

Post-Installation: Connect to Your AI Agent

Claude Desktop

Get the config file path:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the MATLAB MCP server:

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

Restart Claude Desktop.

Claude Code (CLI)

# Add the server to your Claude setup
claude mcp add matlab -- matlab-mcp

# List registered servers
claude mcp list

Cursor

Open .cursor/mcp.json (or create it):

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

Restart Cursor.

Custom MCP Client

For any custom MCP client or agent framework:

stdio transport:

matlab-mcp

SSE transport:

matlab-mcp --transport sse
# Then connect to http://localhost:8765/sse

Verification Checklist

After installation, verify everything is working:

# 1. Check the CLI is available
matlab-mcp --help

# 2. Start the server (stdio mode, Ctrl+C to stop)
matlab-mcp

# 3. In another terminal, verify MATLAB integration
python -c "import matlab.engine; print('✓ MATLAB Engine API works')"

# 4. Test code execution via CLI (basic smoke test)
python -c "
from matlab_mcp.server import create_server
from matlab_mcp.config import AppConfig
server = create_server(AppConfig())
print('✓ Server initialization works')
"

Expected output:

✓ MATLAB Engine API works
✓ Server initialization works
matlab-mcp started. Press Ctrl+C to stop.

Troubleshooting

Problem	Solution
`ModuleNotFoundError: No module named 'matlab'`	Install MATLAB Engine API: `pip install /path/to/matlab/extern/engines/python`
`matlab-mcp: command not found`	Activate your virtual environment: `source .venv/bin/activate`
`MATLAB engine startup timeout`	Increase `pool.startup_timeout` in config; MATLAB can be slow on first boot
`Port 8765 already in use` (SSE mode)	Kill the existing process or use `--port 9000`
Docker fails to find MATLAB	Ensure the volume mount path is correct and readable
Windows `install.bat` fails	Try running PowerShell as Administrator, or manually run: `python -m venv .venv` and `pip install -r requirements.txt`

Configuration

After installation, you can optionally customize behavior via config.yaml:

server:
  transport: stdio        # or 'sse' for multi-user
  logging: INFO

pool:
  min_engines: 1
  max_engines: 4
  startup_timeout: 60

execution:
  sync_timeout: 30        # Auto-promote to async after 30s
  max_output_size_mb: 10

security:
  blocked_functions_enabled: true
  max_upload_size_mb: 100

Place it next to the matlab-mcp binary or use --config /path/to/config.yaml.

Next Steps

Configuration Guide — Customize pool size, timeouts, security
Custom Tools Guide — Expose your own MATLAB functions
Examples — See ready-to-run MATLAB code samples
Architecture — Understand the system design
FAQ — Common questions and answers

Installation

Installation

Prerequisites

System Requirements

macOS Specifics

Windows Specifics

Installation Methods

Method 1: Install from PyPI (Recommended)

Step 1a: Install MATLAB Engine API

macOS

Windows

Verify MATLAB Engine Installation

Step 1b: Install the MCP Server

Step 1c: Verify Installation

Method 2: Install from Source

Step 2a: Clone the Repository

Step 2b: Create a Virtual Environment

Step 2c: Install MATLAB Engine API (if not already done)

Step 2d: Install the Server with Dependencies

Step 2e: Verify Installation

Method 3: Offline Installation (Windows Batch Script)

Step 3a: Run the Offline Installer

Step 3b: Activate and Use

Method 4: Docker

Step 4a: Build the Docker Image

Step 4b: Run with Your MATLAB Installation

Step 4c: Using Docker Compose

Step 4d: Verify Docker Container

Post-Installation: Connect to Your AI Agent

Claude Desktop

Claude Code (CLI)

Cursor

Custom MCP Client

Verification Checklist

Troubleshooting

Configuration

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