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]" — Add monitoring support (health checks, metrics dashboard)

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 on localhost:8765
matlab-mcp --transport sse

# With custom config
matlab-mcp --config my_config.yaml

# With custom tools
matlab-mcp --custom-tools custom_tools.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

Using Dockerfile

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

Using docker-compose

# Clone the repo (if not already done)
git clone https://github.com/HanSur94/matlab-mcp-server-python.git
cd matlab-mcp-server-python

# Edit docker-compose.yml to set your MATLAB installation path
# macOS: /Applications/MATLAB_R2024a.app:/opt/matlab:ro
# Linux: /usr/local/MATLAB/R2024a:/opt/matlab:ro

docker compose up

Example docker-compose.yml volumes section (macOS):

volumes:
  - /Applications/MATLAB_R2024a.app:/opt/matlab:ro
  - ./config.yaml:/app/config.yaml:ro
  - ./custom_tools.yaml:/app/custom_tools.yaml:ro
  - results:/app/results
  - monitoring_data:/app/monitoring

Docker Notes

• The Docker image does not include MATLAB — you must mount your own installation
• Expose ports: 8765 (SSE), 8766 (monitoring health endpoint)
• Set MATLAB_MCP_POOL_MATLAB_ROOT to the path where MATLAB is mounted inside the container
• The image uses python:3.12-slim as the base

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

# Run
matlab-mcp

Configuration

All settings can be overridden via environment variables or a config.yaml file:

# 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)
export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60

# Override transport
export MATLAB_MCP_SERVER_TRANSPORT=sse

# Override MATLAB root
export MATLAB_MCP_POOL_MATLAB_ROOT=/path/to/MATLAB

See Configuration in the wiki for all available settings.

Custom Tools

Expose your proprietary MATLAB functions as first-class AI tools via a YAML file:

matlab-mcp --custom-tools custom_tools.yaml

Example custom_tools.yaml:

tools:
  - name: analyze_signal
    matlab_function: mylib.analyze_signal
    description: "Analyze a signal and return frequency components, SNR, and peak detection"
    parameters:
      - name: signal_path
        type: string
        required: true
      - name: sample_rate
        type: float
        required: true
      - name: window_size
        type: int
        default: 1024
    returns: "Struct with fields: frequencies, magnitudes, snr, peaks"

Troubleshooting

MATLAB Engine Not Found

Ensure the MATLAB Engine API is installed:

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

If not found, reinstall from your MATLAB installation directory.

Port Already in Use

If port 8765 is busy, override it:

export MATLAB_MCP_SERVER_PORT=8766
matlab-mcp --transport sse

Docker: "MATLAB_ROOT not accessible"

Ensure the volume mount path is correct and MATLAB Engine API is installed inside the container or in your mounted MATLAB installation.

Upgrading

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

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