Installation

Prerequisites

Python 3.10+ (3.12 recommended for best performance)
MATLAB R2020b+ installed locally
MATLAB Engine API for Python — comes with MATLAB, requires separate installation
Operating System: macOS, Windows, or Linux with MATLAB support

macOS note: The MATLAB Engine API supports a maximum of 4 concurrent engines due to licensing restrictions. Configure max_engines: 4 in your settings.

Installation Overview

graph LR
    A["MATLAB Installation<br/>R2020b+"] -->|Engine API| B["Python Environment<br/>3.10+"]
    B -->|Install matlab-mcp-python| C["MCP Server"]
    C -->|stdio/SSE| D["Claude Desktop<br/>Cursor/Code"]
    E["config.yaml"] -->|Configure| C
    F["Docker Optional"] -.->|Alt Deploy| C

Step 1: Install MATLAB Engine API for Python

The MATLAB Engine API allows Python to call MATLAB. It's included with MATLAB but must be installed separately into your Python environment.

macOS

# Find your MATLAB installation
ls /Applications/MATLAB*.app

# Install Engine API (adjust version as needed)
cd /Applications/MATLAB_R2024a.app/extern/engines/python
pip install .

# Verify
python -c "import matlab.engine; print('✓ MATLAB Engine API installed')"

Windows

# Find your MATLAB installation
dir "C:\Program Files\MATLAB"

# Open Command Prompt as Administrator and run:
cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"
pip install .

# Verify
python -c "import matlab.engine; print('✓ MATLAB Engine API installed')"

Linux

# Install Engine API (adjust version as needed)
cd /opt/MATLAB/R2024a/extern/engines/python
pip install .

# Verify
python -c "import matlab.engine; print('✓ MATLAB Engine API installed')"

Verify Installation

python << 'EOF'
import matlab.engine
eng = matlab.engine.start_matlab()
result = eng.eval("2 + 2", nargout=1)
print(f"2 + 2 = {result}")
eng.quit()
EOF

Expected output: 2 + 2 = 4

Step 2: Create a Virtual Environment (Recommended)

Isolate the server's dependencies from your system Python:

# Create virtual environment
python3.10 -m venv matlab-mcp-env
source matlab-mcp-env/bin/activate  # macOS/Linux
# matlab-mcp-env\Scripts\activate   # Windows

# Upgrade pip
pip install --upgrade pip

Important: Install the MATLAB Engine API into this virtual environment after activation.

Step 3: Install the MATLAB MCP Server

Option A: From PyPI (Recommended)

# Minimal install (core only)
pip install matlab-mcp-python

# With monitoring dashboard
pip install "matlab-mcp-python[monitoring]"

# With all development tools
pip install "matlab-mcp-python[dev]"

Option B: From Source (Development)

git clone https://github.com/HanSur94/matlab-mcp-server-python.git
cd matlab-mcp-server-python

# Minimal install
pip install -e .

# With monitoring
pip install -e ".[monitoring]"

# With dev dependencies (tests, docs)
pip install -e ".[dev]"

Option C: Offline Installation (Windows)

For systems without internet access:

# On a connected machine:
python update_vendor.bat

# Transfer the vendor/ directory to the offline machine

# On the offline machine:
install.bat

The batch script installs Python 3.10+ and dependencies from local wheels without requiring admin rights.

Option D: Docker

Build and run the server in a container:

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

# Run with MATLAB mounted
docker run -d \
  --name matlab-mcp \
  -p 8765:8765 \
  -p 8766:8766 \
  -v /path/to/MATLAB:/opt/matlab:ro \
  -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab \
  matlab-mcp:latest

# Or using docker-compose
docker compose up -d

Note: Docker image does not include MATLAB. You must mount your local MATLAB installation. See docker-compose.yml for volume configuration.

Step 4: Create Configuration File (Optional)

Create a config.yaml for your deployment:

Minimal Configuration (Development)

server:
  name: "matlab-mcp-dev"
  transport: stdio
  log_level: info

pool:
  min_engines: 1
  max_engines: 2

execution:
  sync_timeout: 30
  workspace_isolation: true

security:
  blocked_functions_enabled: true

Multi-User Configuration (Production)

server:
  name: "matlab-mcp-prod"
  transport: sse
  host: "127.0.0.1"
  port: 8765
  log_level: info

pool:
  min_engines: 4
  max_engines: 16
  health_check_interval: 60

execution:
  sync_timeout: 60
  workspace_isolation: true

sessions:
  max_sessions: 100
  session_timeout: 7200

security:
  blocked_functions_enabled: true
  require_proxy_auth: true
  max_upload_size_mb: 200

monitoring:
  enabled: true
  sample_interval: 10

See Configuration for all available options.

Step 5: Start the Server

Standard Usage (stdio transport)

# Single user with default config
matlab-mcp

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

# Debug mode (verbose logging)
MATLAB_MCP_SERVER_LOG_LEVEL=debug matlab-mcp

Multi-User (SSE transport)

# Start with SSE transport
matlab-mcp --transport sse

# Accessible at http://localhost:8765/sse
# Place behind a reverse proxy (nginx, Caddy) with authentication

Verify Server is Running

# Test stdio connection (should hang, waiting for client)
echo "exit" | matlab-mcp

# Test SSE health endpoint
curl http://localhost:8765/health
# Returns: {"status": "healthy", "uptime_seconds": 1.23, ...}

# View monitoring dashboard (if monitoring enabled)
# Open http://localhost:8766/dashboard in your browser

Step 6: Connect to Your AI Agent

Claude Desktop (macOS/Windows)

Locate config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add MATLAB MCP server:

{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp",
      "args": ["--config", "/path/to/config.yaml"]
    }
  }
}

Restart Claude Desktop
Open a conversation and verify MATLAB tools are available

Claude Code (VS Code Extension)

# Add via CLI
claude mcp add matlab -- matlab-mcp

# Or edit .claude/mcp.json:

{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp"
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp",
      "args": ["--config", "./config.yaml"]
    }
  }
}

Reload Cursor

Custom MCP Client

import json
from subprocess import Popen, PIPE

# Start server
proc = Popen(["matlab-mcp"], stdin=PIPE, stdout=PIPE, stderr=PIPE, text=True)

# Send MCP initialization message
init_msg = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
        "protocolVersion": "2024-11-05",
        "capabilities": {},
        "clientInfo": {"name": "test-client", "version": "1.0"}
    }
}

proc.stdin.write(json.dumps(init_msg) + "\n")
proc.stdin.flush()

# Read response
response = json.loads(proc.stdout.readline())
print(response)

SSE Multi-User Deployment

Deploy behind a reverse proxy with authentication:

Nginx Example:

server {
    listen 443 ssl http2;
    server_name matlab.company.com;

    ssl_certificate /etc/ssl/certs/cert.pem;
    ssl_certificate_key /etc/ssl/private/key.pem;

    # Basic authentication
    auth_basic "MATLAB MCP";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location /sse {
        proxy_pass http://localhost:8765/sse;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_read_timeout 600s;
    }

    location /health {
        proxy_pass http://localhost:8765/health;
    }
}

Step 7: Verification

Test your installation end-to-end:

Local Test

# Test MATLAB execution
python << 'EOF'
import asyncio
from matlab_mcp.server import create_server
from matlab_mcp.config import load_config

async def test():
    config = load_config()
    server = await create_server(config)
    
    # Execute simple code
    result = await server.execute_code(
        code="x = [1 2 3]; sum(x)",
        session_id="test"
    )
    print(result)
    
    await server.shutdown()

asyncio.run(test())
EOF

Agent Test (Claude Desktop)

Start a conversation in Claude Desktop
Type: "What is 2+2 in MATLAB?"
Verify Claude uses the execute_code tool
Confirm result is 4

HTTP Test (SSE only)

# Start server
matlab-mcp --transport sse &

# Test health endpoint
curl -i http://localhost:8765/health
# Returns 200 OK

# Test metrics endpoint
curl http://localhost:8765/metrics | jq .

# View dashboard
open http://localhost:8766/dashboard  # macOS
# xdg-open http://localhost:8766/dashboard  # Linux

Troubleshooting

Issue	Solution
`ModuleNotFoundError: No module named 'matlab'`	Install MATLAB Engine API: `cd /Applications/MATLAB_R2024a.app/extern/engines/python && pip install .`
`Connection refused` when connecting agent	Ensure server is running with `matlab-mcp`, check firewall
`Engine startup timeout`	Increase `engine_start_timeout` in config (default 120s)
`Max 4 engines on macOS`	This is a MATLAB licensing limit; set `max_engines: 4` in config
`Docker: MATLAB not found`	Mount MATLAB: `-v /path/to/MATLAB:/opt/matlab:ro` and set `MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab`
Slow first execution	MATLAB engines take time to start; initial requests may take 30+ seconds

For more help, see Troubleshooting or open a GitHub issue.

Next Steps

Configure: See Configuration for all server options
Learn tools: Review MCP Tools Reference for available functions
Custom tools: Add your MATLAB functions via Custom Tools
Examples: Run Examples to understand capabilities
Architecture: Read Architecture for system design details
Async jobs: Learn about Async Jobs for long-running code
Security: Review Security before production deployment

Installation

Installation

Prerequisites

Installation Overview

Step 1: Install MATLAB Engine API for Python

macOS

Windows

Linux

Verify Installation

Step 2: Create a Virtual Environment (Recommended)

Step 3: Install the MATLAB MCP Server

Option A: From PyPI (Recommended)

Option B: From Source (Development)

Option C: Offline Installation (Windows)

Option D: Docker

Step 4: Create Configuration File (Optional)

Minimal Configuration (Development)

Multi-User Configuration (Production)

Step 5: Start the Server

Standard Usage (stdio transport)

Multi-User (SSE transport)

Verify Server is Running

Step 6: Connect to Your AI Agent

Claude Desktop (macOS/Windows)

Claude Code (VS Code Extension)

Cursor

Custom MCP Client

SSE Multi-User Deployment

Step 7: Verification

Local Test

Agent Test (Claude Desktop)

HTTP Test (SSE only)

Troubleshooting

Next Steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally