Installation

Installation

Prerequisites

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

Step 1: Install MATLAB Engine API

The MATLAB Engine API lets Python call MATLAB. Install it from your MATLAB installation:

macOS

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

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

Windows

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

Linux

cd /usr/local/MATLAB/R2024a/extern/engines/python
pip install .

Verify Installation

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

Step 2: Install the MCP Server

Option A: Install from PyPI

pip install matlab-mcp-python

Option B: Install from source

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

Note: The [dev] extras include all optional dependencies (testing, monitoring). For a minimal install without dev/monitoring dependencies, use pip install -e . instead. To add only monitoring support (dashboard, health endpoint), use pip install -e ".[monitoring]".

Windows (One-Click Installer)

For Windows 10/11, use the bundled offline installer — no admin rights needed:

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

The installer auto-detects MATLAB, creates a virtual environment, and installs everything from bundled wheels — fully offline, no internet required.

Step 3: Run

# Single user (stdio transport) — simplest setup
matlab-mcp

# Multi-user (SSE transport) — shared server
matlab-mcp --transport sse

# With custom config
matlab-mcp --config my_config.yaml

Step 4: Connect to Your AI Agent

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"
    }
  }
}

Claude Code

claude mcp add matlab -- matlab-mcp

Cursor

Add to .cursor/mcp.json in your project:

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

SSE Transport (Multi-User)

Start the server:

matlab-mcp --transport sse

Then point your client to http://localhost:8765/sse.

Docker Installation

Using Dockerfile

# Build the image
docker build -t matlab-mcp .

# Run with your MATLAB mounted
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

Using Docker Compose

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

services:
  matlab-mcp:
    build: .
    ports:
      - "8765:8765"
      - "8766:8766"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
      - ./custom_tools.yaml:/app/custom_tools.yaml:ro
      # Mount your MATLAB installation (adjust for your system):
      # - /usr/local/MATLAB/R2024b:/opt/matlab:ro          # Linux
      # - /Applications/MATLAB_R2024b.app:/opt/matlab:ro    # macOS
      - results:/app/results
    environment:
      - MATLAB_MCP_SERVER_TRANSPORT=sse
      - MATLAB_MCP_POOL_MAX_ENGINES=4
      # - MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab

Then start the server:

docker compose up

Note: The Docker image does not include MATLAB. You must mount your own MATLAB installation and ensure the MATLAB Engine API for Python is accessible inside the container.

Virtual Environment (Recommended)

python -m venv .venv
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 .

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

Environment Variables

Override configuration settings via environment variables:

# Pool settings
export MATLAB_MCP_POOL_MIN_ENGINES=2
export MATLAB_MCP_POOL_MAX_ENGINES=10
export MATLAB_MCP_POOL_MATLAB_ROOT=/path/to/MATLAB

# Execution settings
export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60

# Server settings
export MATLAB_MCP_SERVER_TRANSPORT=sse
export MATLAB_MCP_SERVER_HOST=0.0.0.0
export MATLAB_MCP_SERVER_PORT=8765
export MATLAB_MCP_SERVER_LOG_LEVEL=info

See config.yaml for the complete list of configurable options.

Upgrading

If you previously installed as matlab-mcp-server, uninstall first:

pip uninstall matlab-mcp-server
pip install matlab-mcp-python