Installation

Installation

Prerequisites

• Python 3.10, 3.11, or 3.12
• MATLAB 2020b+ 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).

Linux

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

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

Installation variants:

• Minimal install (no dev/monitoring): pip install -e .
• With dev tools (testing, linting): pip install -e ".[dev]"
• With monitoring (dashboard, health endpoint): pip install -e ".[monitoring]"
• Full (everything): pip install -e ".[dev]"

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.

Access the web dashboard at http://localhost:8766/dashboard.

Step 5: Docker Setup

Build the Docker Image

docker build -t matlab-mcp .

Run with Docker

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

Platform-specific MATLAB paths:

• Linux: -v /usr/local/MATLAB/R2024b:/opt/matlab:ro
• macOS: -v /Applications/MATLAB_R2024b.app:/opt/matlab:ro
• Windows: -v "C:\Program Files\MATLAB\R2024b:/opt/matlab:ro"

Run with Docker Compose

Edit docker-compose.yml to set your MATLAB installation path in the volumes section:

volumes:
  # Uncomment and adjust for your system:
  # - /usr/local/MATLAB/R2024b:/opt/matlab:ro          # Linux
  # - /Applications/MATLAB_R2024b.app:/opt/matlab:ro    # macOS
  # - C:\Program Files\MATLAB\R2024b:/opt/matlab:ro     # Windows

Then start the stack:

docker compose up

Access the server at http://localhost:8765 and the dashboard at http://localhost:8766/dashboard.

Note: The Docker image does not include MATLAB. You must mount your own MATLAB installation and set the MATLAB_MCP_POOL_MATLAB_ROOT environment variable or uncomment the volume mount in docker-compose.yml.

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

Upgrading from matlab-mcp-server

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

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

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

See the Configuration documentation for all available settings.