Installation

Installation

Prerequisites

• Python 3.10+ (tested on 3.10, 3.11, 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).

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

Installation variants:

• pip install -e . — Minimal install (core dependencies only)
• pip install -e ".[dev]" — Full install with testing, linting, and monitoring tools
• pip install -e ".[monitoring]" — Core + monitoring support (psutil, uvicorn for health endpoints and metrics)

Core dependencies:

• fastmcp>=2.0.0,<3.0.0
• pydantic>=2.0.0
• pyyaml>=6.0
• Pillow>=9.0.0
• aiosqlite>=0.19.0
• plotly>=5.9.0

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

# SSE with specific host/port
matlab-mcp --transport sse --host 0.0.0.0 --port 8765

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/Web)

Start the server with SSE transport:

matlab-mcp --transport sse

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

Docker Installation

Build and Run with Docker

# 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

Path examples:

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

Docker Compose

Create or 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 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  # 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 the MATLAB Engine API for Python must be accessible inside the container.

Docker Health Check

The container includes a built-in health check that polls http://localhost:8765/health every 30 seconds. To disable or customize:

docker run --no-healthcheck matlab-mcp

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
cd /path/to/matlab-mcp-server-python
pip install -e ".[dev]"

# Verify
matlab-mcp --help

Environment Variables

Override configuration at runtime:

# 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=debug

# Run with overrides
matlab-mcp --transport sse

Upgrading

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

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

Troubleshooting

MATLAB Engine API Not Found

Ensure MATLAB Engine API is installed in the same Python environment:

import matlab.engine
print(matlab.engine.__file__)  # Should show path in your venv or system Python

If missing, reinstall:

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

Docker MATLAB Not Found

Verify the MATLAB mount path exists and MATLAB Engine API is available:

docker run -it matlab-mcp bash
python -c "import matlab.engine; print('OK')"

If it fails, reinstall MATLAB Engine API inside the container by extending the Dockerfile:

RUN cd /opt/matlab/extern/engines/python && pip install .

Server Won't Start on Port

Ensure the port is available:

lsof -i :8765  # macOS/Linux
netstat -ano | findstr :8765  # Windows

Or specify a different port:

matlab-mcp --transport sse --port 9000