Installation

Installation

Prerequisites

• Python 3.10+ (3.10, 3.11, or 3.12 supported)
• 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).

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.0
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 dependencies):

  pip install -e .

• With development tools (testing, linting, auditing):

  pip install -e ".[dev]"

• With monitoring support only (dashboard, health checks):

  pip install -e ".[monitoring]"

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

# Multi-user with custom config
matlab-mcp --transport sse --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

Dockerfile

The project includes a Dockerfile that packages the server with all dependencies. The image is based on python:3.12-slim and exposes ports 8765 (SSE) and 8766 (monitoring).

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

# Run with your MATLAB installation 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 mount paths:

• macOS: -v /Applications/MATLAB_R2024b.app:/opt/matlab:ro
• Linux: -v /usr/local/MATLAB/R2024b:/opt/matlab:ro
• Windows (WSL2): -v /mnt/c/Program\ Files/MATLAB/R2024b:/opt/matlab:ro

Docker Compose

The project includes a docker-compose.yml for simplified multi-container setup:

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

# Run in detached mode:
docker compose up -d

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

# Stop:
docker compose down

Configure MATLAB path in 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
      # Uncomment and adjust for your system:
      # - /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

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.

Docker Health Check

The container includes a health check that verifies the server is responding:

docker run --health-interval=30s --health-timeout=5s --health-retries=3 \
  -p 8765:8765 matlab-mcp --transport sse

Virtual Environment (Recommended)

# Create and activate virtual environment
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 and development dependencies
cd /path/to/matlab-mcp-server-python
pip install -e ".[dev]"

Configuration

Configuration is managed via 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 for Docker
export MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab

See the Configuration section in the wiki for all available settings.

Troubleshooting

MATLAB Engine API Not Found

Ensure you've installed the MATLAB Engine API from your MATLAB installation (Step 1). Verify with:

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

Docker MATLAB Not Found

Check that:

1. The MATLAB mount path is correct for your system
2. The MATLAB_MCP_POOL_MATLAB_ROOT environment variable matches the mount path
3. The mount is read-only (:ro) to prevent accidental modifications

Connection Issues

If using SSE transport, verify the server is listening:

curl http://localhost:8765/health

Should return a JSON health status object.

Upgrading

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

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