Installation

Installation

Prerequisites

• Python 3.10, 3.11, or 3.12
• MATLAB R2022b+ with the MATLAB Engine API for Python installed
• MATLAB Engine API for Python — comes with MATLAB, needs separate installation into your Python environment

Step 1: Install MATLAB Engine API for Python

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

macOS

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

Adjust the path for your MATLAB version (e.g., R2022b, 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 (Recommended)

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

Installation variants:

• Minimal install (no dev/monitoring): pip install -e .
• With dev/testing tools: pip install -e ".[dev]" (includes pytest, pytest-asyncio, pytest-cov, ruff, etc.)
• With monitoring only: pip install -e ".[monitoring]" (adds health endpoint and server metrics)

Option C: Windows One-Click Installer (No Admin Required)

For Windows 10/11 with Python 3.10+:

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 the Server

Single-User Mode (stdio transport — simplest)

matlab-mcp

Use this for local development or connecting a single AI client.

Multi-User Mode (SSE transport — shared server)

matlab-mcp --transport sse

This starts an HTTP server on http://localhost:8765 with SSE endpoint at /sse. Multiple clients can connect simultaneously with session isolation.

With Custom Configuration

matlab-mcp --config my_config.yaml
matlab-mcp --transport sse --config /path/to/config.yaml

Step 4: Connect to Your AI Agent

Claude Desktop

Add to your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Docker Installation

Build the Docker Image

docker build -t matlab-mcp .

Run with Docker

# Single-user (stdio) — for testing
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

Platform-specific MATLAB paths:

• Linux: -v /usr/local/MATLAB/R2024b:/opt/matlab:ro
• macOS: -v /Applications/MATLAB_R2024b.app:/opt/matlab:ro
• Windows: (use WSL2 or mount via Docker Desktop settings)

Run with Docker Compose

Create/edit docker-compose.yml:

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 (uncomment and adjust for your OS):
      # - /usr/local/MATLAB/R2024b:/opt/matlab:ro          # Linux
      # - /Applications/MATLAB_R2024b.app:/opt/matlab:ro    # macOS
      - results:/app/results
      - monitoring_data:/app/monitoring
    environment:
      - MATLAB_MCP_SERVER_TRANSPORT=sse
      - MATLAB_MCP_POOL_MAX_ENGINES=4
      # - MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab  # Uncomment when mounting MATLAB

volumes:
  results:
  monitoring_data:

Then run:

docker compose up

Note: The Docker image does not include MATLAB. You must mount your own MATLAB installation and set MATLAB_MCP_POOL_MATLAB_ROOT environment variable to point to it inside the container.

Virtual Environment Setup (Recommended)

For development or isolation:

# Create virtual environment
python -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 .

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

Environment Variables

Override configuration settings without editing config.yaml:

# Pool configuration
export MATLAB_MCP_POOL_MIN_ENGINES=2
export MATLAB_MCP_POOL_MAX_ENGINES=10
export MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab

# Execution settings
export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=30

# 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

Troubleshooting

MATLAB Engine Not Found

Verify the MATLAB Engine API is installed:

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

If this fails, reinstall from your MATLAB installation directory (see Step 1).

Port Already in Use (SSE mode)

The default SSE port is 8765. Change it:

export MATLAB_MCP_SERVER_PORT=9000
matlab-mcp --transport sse

Docker MATLAB Path

Ensure the MATLAB path is correct and mounted read-only:

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

Upgrading

If you previously installed as matlab-mcp-server:

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

The new package name is matlab-mcp-python, and the command remains matlab-mcp.