Skip to content

Installation

Jump to bottom
github-actions[bot] edited this page Apr 3, 2026 · 20 revisions

Installation

Prerequisites

  • Python 3.10+ (3.12 recommended)
  • MATLAB R2022b+ with the MATLAB Engine API for Python installed
  • For Windows without admin: Port 1024+ (default 8765 is OK)
  • For Docker deployments: Docker 20.10+ and docker-compose 2.0+

Step 1: Install MATLAB Engine API for Python

The MATLAB Engine API allows Python to call MATLAB. This is required and separate from MATLAB itself.

graph LR
    A["MATLAB<br/>Installation"] -->|contains| B["extern/engines/python"]
    B -->|pip install| C["MATLAB Engine<br/>for Python"]
    C -->|imported by| D["matlab_mcp server"]
    D -->|controls| E["MATLAB processes"]
Loading

macOS

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

Adjust version in path: R2023b, R2024a, R2024b, etc.

Windows

cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"
pip install .

Linux (with MATLAB installed)

cd /usr/local/MATLAB/R2024a/extern/engines/python
pip install .

Verify Engine API Installation

import matlab.engine
eng = matlab.engine.start_matlab()
result = eng.eval("2 + 2", nargout=1)
print(result)  # Should print 4.0
eng.quit()

If this works, you're ready for the next step.

Step 2: Install the MATLAB MCP Server

Option A: PyPI (Recommended)

pip install matlab-mcp-python

Verify:

matlab-mcp --help

Option B: From Source

git clone https://github.com/HanSur94/matlab-mcp-server-python.git
cd matlab-mcp-server-python
pip install -e ".[dev]"

The [dev] extra includes pytest, ruff, and coverage tools for testing. For a minimal install without dev dependencies, use pip install -e . instead. To include only monitoring support (dashboard, health endpoint), use pip install -e ".[monitoring]".

Option C: Conda Environment

# Create environment from conda file
conda env create -f environment.yml

# Or create and install manually
conda create -y -n matlab-mcp python=3.12
conda activate matlab-mcp
pip install matlab-engine
pip install matlab-mcp-python

Option D: Docker

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

# Build image
docker build -t matlab-mcp .

# Run with mounted MATLAB installation
docker run -it -p 8765:8765 \
  -v /path/to/MATLAB:/opt/matlab:ro \
  -e MATLAB_ROOT=/opt/matlab \
  matlab-mcp

Or with Docker Compose (edit docker-compose.yml to set your MATLAB path):

docker-compose up

Note: The Docker image does not include MATLAB. You must provide your own MATLAB installation as a mount point.

Option E: Windows (One-Click Installer, No Admin)

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

The install.bat script:

  1. Auto-detects Python and MATLAB installations
  2. Installs MATLAB Engine API
  3. Creates a Python virtual environment
  4. Installs the server and all dependencies
  5. Works fully offline from bundled wheels
  6. Requires no admin rights on Windows 10/11

Step 3: Verify Installation

Test MATLAB Execution

# Start server in inspect mode (no MATLAB needed for this test)
matlab-mcp --inspect

# In another terminal, test via Python
python -c "
from matlab_mcp.server import MatlabMCPServer
from matlab_mcp.config import load_config
config = load_config()
print(f'Config loaded: {config.server.transport}')
print('✓ Server core working')
"

Generate an Auth Token

If using HTTP transport with authentication:

matlab-mcp --generate-token
# Output:
# Bearer token (copy to env var):
# export MATLAB_MCP_AUTH_TOKEN=a1b2c3d4e5f6...
# 
# For Windows (cmd):
# set MATLAB_MCP_AUTH_TOKEN=a1b2c3d4e5f6...
#
# For PowerShell:
# $env:MATLAB_MCP_AUTH_TOKEN='a1b2c3d4e5f6...'

Step 4: Start the Server

Stdio Transport (Single User, Local)

Simplest setup — no network, perfect for Claude Desktop:

matlab-mcp

Output:

Starting MATLAB MCP Server (v2.0)
Transport: stdio
Config: (defaults)
MATLAB engine pool: 2-4 engines
✓ Startup complete

Then configure your AI agent (see step 5).

SSE Transport (Multi-User, Deprecated)

For shared server access (being phased out in favor of streamable HTTP):

matlab-mcp --transport sse --host 127.0.0.1 --port 8765

Output:

Starting MATLAB MCP Server (v2.0)
Transport: SSE (deprecated, use streamable HTTP)
Server: http://127.0.0.1:8765/sse
Monitor: http://127.0.0.1:8766
Pool: 2-10 engines (auto-scaling)
✓ Startup complete

HTTP/Streamable Transport (Multi-User, Modern)

Recommended for remote agents and CI/CD:

# Generate a token first (optional but recommended)
MATLAB_MCP_AUTH_TOKEN=$(matlab-mcp --generate-token | grep "^[a-f0-9]" | head -1)
export MATLAB_MCP_AUTH_TOKEN

# Start server
matlab-mcp --transport streamablehttp --host 127.0.0.1 --port 8765

Output:

Starting MATLAB MCP Server (v2.0)
Transport: streamable HTTP
Endpoint: http://127.0.0.1:8765/mcp
Auth: Bearer token required (MATLAB_MCP_AUTH_TOKEN)
Monitor: http://127.0.0.1:8766
Pool: 2-10 engines (auto-scaling)
✓ Startup complete

Configuration via environment variables:

export MATLAB_MCP_SERVER_HOST=127.0.0.1
export MATLAB_MCP_SERVER_PORT=8765
export MATLAB_MCP_SERVER_TRANSPORT=streamablehttp
export MATLAB_MCP_POOL_MIN_ENGINES=2
export MATLAB_MCP_POOL_MAX_ENGINES=10
matlab-mcp

Step 5: Connect an AI Agent

Claude Desktop

  1. Open Claude Desktop config:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Add the MATLAB server:

{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp"
    }
  }
}
  1. Restart Claude Desktop — MATLAB tools will appear in the tool picker.

Claude Code

# Install or update the server in Claude Code
claude mcp add matlab

Or manually:

# Edit your Claude Code config
claude config edit

# Add under mcpServers:
# {
#   "matlab": {
#     "command": "matlab-mcp"
#   }
# }

Cursor

  1. Open Cursor settings → MCP
  2. Click Add MCP and fill:
    • Name: matlab
    • Command: matlab-mcp
    • Type: command
  3. Save and restart Cursor

Or edit .cursor/mcp.json directly:

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

Codex CLI (Remote, Streamable HTTP)

# Start the server with auth token
export MATLAB_MCP_AUTH_TOKEN=$(matlab-mcp --generate-token | grep "^[a-f0-9]" | head -1)
matlab-mcp --transport streamablehttp

# In another terminal, connect Codex
codex connect http://127.0.0.1:8765/mcp \
  --header "Authorization: Bearer $MATLAB_MCP_AUTH_TOKEN"

Generic HTTP Clients (Python, JavaScript, etc.)

import httpx
import json

# Start server with bearer token
# matlab-mcp --transport streamablehttp
# export MATLAB_MCP_AUTH_TOKEN=<token>

token = "YOUR_TOKEN_HERE"
url = "http://127.0.0.1:8765/mcp"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Initialize session
payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
        "protocolVersion": "2024-11-05",
        "capabilities": {},
        "clientInfo": {"name": "my-client", "version": "1.0"}
    }
}

async with httpx.AsyncClient() as client:
    response = await client.post(url, json=payload, headers=headers)
    print(response.json())

Step 6: Test the Connection

Once your agent is configured, run a test:

Claude Desktop

  1. Open a conversation
  2. Click the tools icon (hammer)
  3. Look for MATLAB tools: execute_code, get_workspace, list_toolboxes, etc.
  4. Ask Claude: "Can you run MATLAB code? Try computing 2+2."

Expected response: Claude will use the execute_code tool and return 4.

Cursor

  1. Open a new file
  2. Use Ctrl+K (Mac: Cmd+K) to open the command palette
  3. Type "MATLAB" — you should see available MATLAB tools
  4. Ask: "Run MATLAB code that computes factorial(5)"

Codex CLI

codex --mcp matlab "Generate MATLAB code that plots sin(x) from 0 to 2π"

System Requirements

graph TB
    subgraph Runtime
        A["Python 3.10+"]
        B["MATLAB R2022b+"]
    end
    subgraph Python Packages
        C["fastmcp ≥3.2.0"]
        D["pydantic ≥2.11.7"]
        E["matlab-engine"]
    end
    subgraph Optional
        F["Docker 20.10+"]
        G["Conda"]
        H["psutil for monitoring"]
    end
    A --> C
    B --> E
    C --> D
    F -.-> A
    G -.-> A
    H -.-> A
Loading
Component Minimum Recommended Notes
Python 3.10 3.12 3.12 has best MATLAB compatibility
MATLAB R2022b R2024a+ Engine API required; Simulink optional
Disk Space 500 MB 2 GB Server + dependencies; MATLAB installation separate
Memory 2 GB 4+ GB Per MATLAB engine instance; scales with pool size
Network N/A Gigabit For remote HTTP transport (SSE/streamable)
Admin Rights No No Windows: port binding requires UAC elevation only for ports <1024

Troubleshooting Installation

"ModuleNotFoundError: No module named 'matlab.engine'"

Cause: MATLAB Engine API for Python not installed.

Fix:

cd /Applications/MATLAB_R2024a.app/extern/engines/python  # macOS
pip install .

Or re-run install.bat on Windows.

"MATLAB_ROOT environment variable not set"

Cause: Server can't find MATLAB installation.

Fix:

# macOS/Linux
export MATLAB_ROOT=/Applications/MATLAB_R2024a.app

# Windows (cmd)
set MATLAB_ROOT=C:\Program Files\MATLAB\R2024a

# Windows (PowerShell)
$env:MATLAB_ROOT = "C:\Program Files\MATLAB\R2024a"

matlab-mcp

Or set in config.yaml:

pool:
  matlab_root: /Applications/MATLAB_R2024a.app

"Address already in use" on port 8765

Cause: Another server is already running on that port.

Fix:

# Use a different port
matlab-mcp --port 9000

# Or kill existing process
lsof -ti:8765 | xargs kill -9  # macOS/Linux
netstat -ano | findstr :8765   # Windows (find PID)
taskkill /PID <PID> /F         # Windows (kill process)

Server starts but agent can't connect (stdio)

Cause: Agent not configured correctly.

Fix:

  • Verify config file location: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Ensure command path is correct: which matlab-mcp (should be in PATH)
  • Check for typos in JSON syntax (use a JSON validator)
  • Restart the agent application completely (close and reopen)

Server starts but agent can't connect (HTTP/SSE)

Cause: Firewall or network routing issue.

Fix:

# Test local connectivity
curl http://127.0.0.1:8765/health

# Test with bearer token
export TOKEN=<your-token>
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/health

# Check firewall
sudo lsof -i :8765  # macOS/Linux
netsh advfirewall firewall add rule name="MATLAB MCP" dir=in action=allow program="python.exe" localport=8765 protocol=tcp  # Windows

Docker: "No such file or directory: /opt/matlab"

Cause: MATLAB mount path doesn't exist in container.

Fix:

# Verify your MATLAB installation path exists
ls /opt/matlab/bin/matlab

# Update docker-compose.yml with correct path
# volumes:
#   - /Users/you/MATLAB/R2024a:/opt/matlab:ro

"Broken pipe" or connection drops after 30 seconds

Cause: Reverse proxy timeout or network configuration.

Fix:

# For nginx
proxy_read_timeout 300s;
proxy_connect_timeout 300s;

# For Apache
Timeout 300
ProxyTimeout 300

# Or increase timeout in config.yaml
execution:
  sync_timeout: 120  # seconds

Next Steps

Once installed and verified:

  1. Configuration — Customize pool size, blocked functions, monitoring
  2. Tools Reference — All available tools and their parameters
  3. Examples — Ready-to-run MATLAB code examples
  4. Security — Auth, blocklists, workspace isolation
  5. Custom Tools — Expose your own MATLAB functions as tools

Version Support Matrix

MATLAB Engine API Python 3.10 Python 3.11 Python 3.12 Status
R2022b ✓ ✓ ✓ ⚠ Supported (oldest)
R2023a ✓ ✓ ✓ ⚠ Supported
R2023b ✓ ✓ ✓ ✓ Recommended
R2024a ✓ ✓ ✓ ✓ Recommended
R2024b ✓ ✓ ✓ ✓ Latest

⚠ = Requires workaround; ✓ = Fully tested; ❌ = Not supported

Getting Help

Clone this wiki locally