Installation

Installation

Prerequisites

• Python 3.10+ (3.10, 3.11, 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
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:

• Full install with dev/test dependencies: pip install -e ".[dev]" (recommended for development)
• Minimal install: pip install -e . (production, no testing/monitoring tools)
• With monitoring only: pip install -e ".[monitoring]" (adds dashboard, health endpoints, server metrics)

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.

Step 5: Run with Docker

Dockerfile

The included Dockerfile builds a Python 3.12 image with all dependencies pre-installed:

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 mount paths:

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

Docker Compose

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

docker compose up

Example docker-compose.yml setup:

services:
  matlab-mcp:
    build: .
    ports:
      - "8765:8765"
      - "8766:8766"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
      - ./custom_tools.yaml:/app/custom_tools.yaml:ro
      - /Applications/MATLAB_R2024a.app:/opt/matlab:ro  # macOS
      # - /usr/local/MATLAB/R2024a:/opt/matlab:ro       # Linux
      - 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
volumes:
  results:
  monitoring_data:

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  # macOS
# cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"  # Windows
pip install .

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

Configuration

All settings are configurable via config.yaml or environment variables. Common overrides:

# Pool configuration
export MATLAB_MCP_POOL_MIN_ENGINES=2
export MATLAB_MCP_POOL_MAX_ENGINES=10

# Execution timeouts
export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=30

# Server transport and port
export MATLAB_MCP_SERVER_TRANSPORT=sse
export MATLAB_MCP_SERVER_PORT=8765

# Logging
export MATLAB_MCP_SERVER_LOG_LEVEL=info

See the main README and config.yaml for all available configuration options.

Upgrading

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

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

Troubleshooting

MATLAB Engine API not found

Ensure you installed the MATLAB Engine API in the same Python environment as the MCP server:

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

Docker: MATLAB not accessible

Verify your MATLAB mount path is correct and the directory contains bin/matlab:

docker run -it --rm -v /Applications/MATLAB_R2024a.app:/opt/matlab:ro \
  ubuntu:latest ls -la /opt/matlab/bin/matlab

Port already in use (SSE mode)

If port 8765 is in use, override it:

export MATLAB_MCP_SERVER_PORT=8766
matlab-mcp --transport sse