Installation

Installation

Prerequisites

• Python 3.10–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 .

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, linting, 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]".

Option C: Windows One-Click Installer

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. Works on Windows 10/11 with Python 3.10, 3.11, or 3.12.

Step 3: Run

# Single user (stdio transport)
matlab-mcp

# Multi-user (SSE transport)
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

Build the Image

docker build -t matlab-mcp .

Run with Mounted MATLAB

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 --transport sse

macOS example:

docker run -p 8765:8765 -p 8766:8766 \
  -v /Applications/MATLAB_R2024a.app:/opt/matlab:ro \
  -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab \
  matlab-mcp --transport sse

Linux example:

docker run -p 8765:8765 -p 8766:8766 \
  -v /usr/local/MATLAB/R2024b:/opt/matlab:ro \
  -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab \
  matlab-mcp --transport sse

Using docker-compose

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

docker compose up

The docker-compose.yml includes service definitions with volumes for results and monitoring data:

volumes:
  - ./config.yaml:/app/config.yaml:ro
  - ./custom_tools.yaml:/app/custom_tools.yaml:ro
  - /Applications/MATLAB_R2024a.app:/opt/matlab:ro  # Adjust for your system
  - results:/app/results
  - monitoring_data:/app/monitoring

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

Configuration

All settings live in config.yaml with sensible defaults. Override any setting via environment variables:

# Override pool size
export MATLAB_MCP_POOL_MIN_ENGINES=4
export MATLAB_MCP_POOL_MAX_ENGINES=16

# Override sync timeout (promote to async after 60s instead of 30s)
export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60

# Override transport
export MATLAB_MCP_SERVER_TRANSPORT=sse

# Override MATLAB root directory (for Docker or non-standard installs)
export MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab

See Configuration for all available options.

Troubleshooting

MATLAB Engine API Not Found

Ensure you've installed the MATLAB Engine API into the same Python environment as the server:

# Activate your venv first
source .venv/bin/activate

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

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

Docker MATLAB Not Detected

Verify the mount path is correct and MATLAB Engine API is installed in the container's Python. You can test inside the container:

docker run -it \
  -v /Applications/MATLAB_R2024a.app:/opt/matlab:ro \
  -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab \
  matlab-mcp bash

# Inside container:
python -c "import matlab.engine; print('OK')"

Upgrading from Old Package Name

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

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