Skip to content

Installation

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

Installation

Prerequisites

  • Python 3.10+
  • MATLAB R2022b+ installed locally
  • MATLAB Engine API for Python — comes with MATLAB, needs separate install

System Requirements

  • macOS: 10.15+ (note: max 4 concurrent engines due to stability limits)
  • Windows: Windows 10/11
  • Linux: Ubuntu 18.04+ or equivalent

Installation Methods

graph TD
    A["Choose Installation Method"] --> B["Package Manager"]
    A --> C["From Source"]
    A --> D["Docker"]
    
    B --> B1["pip install matlab-mcp-python"]
    C --> C1["git clone + pip install -e"]
    D --> D1["docker build + docker run<br/>or docker-compose up"]
    
    B1 --> E["Install MATLAB Engine API"]
    C1 --> E
    D1 --> F["Mount MATLAB + verify"]
    
    E --> G["Run matlab-mcp"]
    F --> G
    
    G --> H["Connect to AI Agent"]
Loading

Step 1: Install MATLAB Engine API for Python

The MATLAB Engine API lets Python call MATLAB. It comes bundled with MATLAB but must be installed as a Python package.

macOS

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

# Install into Python (system or virtual environment)
pip install .

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

Verify:

python3 -c "import matlab.engine; eng = matlab.engine.start_matlab(); print(eng.eval('version')); eng.quit()"

Windows (Administrator PowerShell)

# Using a command prompt (no special privileges needed)
cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"
pip install .

# Or use the provided installer
.\install.bat

The install.bat script automates detection of Python 3.10+ and MATLAB R2022b+ installations, creates a virtual environment, and installs all dependencies offline.

Verify:

python -c "import matlab.engine; eng = matlab.engine.start_matlab(); print(eng.eval('version')); eng.quit()"

Linux

# Adjust the path to your MATLAB installation
cd /opt/MATLAB/R2024a/extern/engines/python
pip install .

Verify:

python -c "import matlab.engine; eng = matlab.engine.start_matlab(); print(eng.eval('version')); eng.quit()"

Step 2: Install the MATLAB MCP Server

Option A: Install from PyPI (Recommended)

# Minimal install (production)
pip install matlab-mcp-python

# With monitoring support (dashboard + health endpoint)
pip install "matlab-mcp-python[monitoring]"

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

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

Option B: Install from Source

# Clone the repository
git clone https://github.com/HanSur94/matlab-mcp-server-python.git
cd matlab-mcp-server-python

# Create virtual environment (optional but recommended)
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate    # Windows

# Install in development mode
pip install -e ".[dev]"

# Or minimal install
pip install -e .

Option C: Docker Setup

Using Docker

# Build the image (requires Dockerfile in repo)
docker build -t matlab-mcp:latest .

# Run with MATLAB mounted (adjust path to your MATLAB installation)
docker run -it \
  -p 8765:8765 \
  -p 8766:8766 \
  -v /Applications/MATLAB_R2024a.app:/opt/matlab:ro \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab \
  matlab-mcp:latest

Windows paths:

docker run -it `
  -p 8765:8765 `
  -p 8766:8766 `
  -v "C:\Program Files\MATLAB\R2024a:C:\MATLAB:ro" `
  -v "$(pwd)\config.yaml:C:\app\config.yaml" `
  -e MATLAB_MCP_POOL_MATLAB_ROOT=C:\MATLAB `
  matlab-mcp:latest

Using Docker Compose

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

# View logs
docker-compose logs -f matlab-mcp

# Stop
docker-compose down

docker-compose.yml example:

version: '3.8'
services:
  matlab-mcp:
    build: .
    ports:
      - "8765:8765"  # SSE API
      - "8766:8766"  # Dashboard
    volumes:
      - /Applications/MATLAB_R2024a.app:/opt/matlab:ro
      - ./config.yaml:/app/config.yaml
      - matlab-results:/app/results
      - matlab-monitoring:/app/monitoring
    environment:
      MATLAB_MCP_POOL_MATLAB_ROOT: /opt/matlab
      MATLAB_MCP_SERVER_TRANSPORT: sse
    restart: unless-stopped

volumes:
  matlab-results:
  matlab-monitoring:

Step 3: Verification

Basic Verification

# Test that matlab-mcp command is available
matlab-mcp --version

# Test MATLAB connectivity (runs a simple command)
matlab-mcp --test

# Show config that will be used
matlab-mcp --config config.yaml --dry-run

Run the Server

# Single-user (stdio transport) - recommended for local use
matlab-mcp

# Multi-user (SSE transport) - for remote/shared deployments
matlab-mcp --transport sse

# With custom config
matlab-mcp --config ./examples/config_multiuser.yaml

# With debug logging
MATLAB_MCP_SERVER_LOG_LEVEL=debug matlab-mcp

# SSE with specific host/port
matlab-mcp --transport sse --host 127.0.0.1 --port 8765

Test Execution

Once running, verify the server is working:

# In another terminal, with the server running:
curl http://localhost:8765/health  # For SSE transport

# Check metrics dashboard (if monitoring enabled)
open http://localhost:8766/dashboard

Step 4: Connect to Your AI Agent

Claude Desktop

  1. macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json
  2. Windows: Edit %APPDATA%\Claude\claude_desktop_config.json 
{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp"
    }
  }
}

Restart Claude Desktop.

Claude Code

claude mcp add matlab -- matlab-mcp

Cursor

Create or edit .cursor/mcp.json:

{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp",
      "args": []
    }
  }
}

Copilot (GitHub Copilot)

Add to your IDE's MCP server configuration (exact location varies by IDE).

Using SSE Transport (Multi-User / Remote)

For multi-user or remote deployments, use SSE:

# Start server
matlab-mcp --transport sse --host 0.0.0.0 --port 8765

# Clients connect to: http://your-server:8765/sse

Security: Always put the SSE server behind a reverse proxy (nginx, Caddy) with authentication enabled. Set require_proxy_auth: true in config.yaml.

Virtual Environment Setup (Recommended)

# Create virtual environment
python3 -m venv .venv

# Activate it
source .venv/bin/activate        # macOS/Linux
# .venv\Scripts\activate          # Windows

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

# Return to project directory and install server
cd /path/to/matlab-mcp-server-python
pip install -e ".[dev]"

# Verify
matlab-mcp --version

Troubleshooting Installation

graph TD
    A["Installation Issues?"] --> B{"MATLAB Engine<br/>imports?"}
    B -->|No| C["Check MATLAB path<br/>reinstall engine API"]
    B -->|Yes| D{"matlab-mcp<br/>command found?"}
    D -->|No| E["Check PATH<br/>pip list"]
    D -->|Yes| F{"Server starts?"}
    F -->|No| G["Check config.yaml<br/>Enable debug logging"]
    F -->|Yes| H{"Connects to agent?"]
    H -->|No| I["Check transport mode<br/>host/port settings"]
    H -->|Yes| J["✓ Ready to use!"]
    
    C --> K["Run verification test"]
    E --> K
    G --> K
    I --> K
    K --> L{Working?}
    L -->|Yes| J
    L -->|No| M["See Troubleshooting wiki"]
Loading

MATLAB Engine API Not Found

Error: ModuleNotFoundError: No module named 'matlab'

Solution:

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

# Verify import
python -c "import matlab.engine; print(matlab.engine.__version__)"

Command Not Found: matlab-mcp

Error: command not found: matlab-mcp or 'matlab-mcp' is not recognized

Solution:

# Check installation
pip list | grep matlab-mcp

# Reinstall
pip install --force-reinstall matlab-mcp-python

# Test
which matlab-mcp  # macOS/Linux
where matlab-mcp  # Windows

macOS Engine Startup Timeout

Symptom: Server hangs for 120+ seconds before responding

Solution:

# config.yaml
pool:
  engine_start_timeout: 300  # Increase to 5 minutes
  max_engines: 2              # Reduce (macOS stability)

Also check that MATLAB is not running heavy background jobs.

Windows: Permission Denied on Virtual Environment

Error: PermissionError during install.bat

Solution:

# Run PowerShell as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
.\install.bat

Or install manually:

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

Docker: MATLAB Not Found

Error: matlab.engine.EngineException: MATLAB is not installed...

Solution:

  1. Verify MATLAB path is mounted correctly:

    docker run -it <image> ls -la /opt/matlab

  2. Set the path correctly:

    docker run -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab ...

  3. Ensure MATLAB Engine API is installed in the container image.

Configuration After Installation

Create or customize config.yaml:

# Minimal configuration
server:
  transport: stdio

pool:
  min_engines: 1
  max_engines: 4

# For multi-user deployments
server:
  transport: sse
  port: 8765

pool:
  min_engines: 2
  max_engines: 16

security:
  require_proxy_auth: true

See Configuration for all available options.

Upgrading from Older Versions

If you previously installed as matlab-mcp-server:

# Uninstall old package
pip uninstall matlab-mcp-server

# Install new package
pip install matlab-mcp-python

# Check for config changes
matlab-mcp --config config.yaml --dry-run

Next Steps

Clone this wiki locally