Skip to content

Installation

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

Installation

Prerequisites

  • Python 3.10+ (3.11 and 3.12 recommended)
  • MATLAB R2022b or newer installed locally
  • MATLAB Engine API for Python — included with MATLAB, requires separate installation

Quick Start

If you're familiar with Python and MATLAB, here's the fastest path:

# 1. Install MATLAB Engine API (macOS example)
cd /Applications/MATLAB_R2024a.app/extern/engines/python && pip install .

# 2. Install MATLAB MCP Server
pip install matlab-mcp

# 3. Run (single-user stdio transport)
matlab-mcp

# 4. Connect via Claude Desktop, Cursor, or Claude Code

Step-by-Step Installation

Step 1: Install MATLAB Engine API for Python

The MATLAB Engine API allows Python to call MATLAB functions. It ships with MATLAB but must be installed into your Python environment.

graph LR A["MATLAB Installation
(R2022b+)"] -->|contains| B["Engine API Source
(extern/engines/python)"] B -->|pip install| C["MATLAB Engine API
(in your Python env)"] C -->|enables| D["matlab.engine
module"]

macOS

# Locate your MATLAB installation
ls /Applications/MATLAB_*.app/

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

Windows (no admin required)

# Locate MATLAB (typically C:\Program Files\MATLAB\)
cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"
pip install .

Or if Python is in your PATH:

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

Linux

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

Verify Installation

python -c "import matlab.engine; eng = matlab.engine.start_matlab(); print('Success'); eng.quit()"

If this hangs, see Troubleshooting below.

Step 2: Install the MATLAB MCP Server

Choose your installation method based on your use case:

Option A: PyPI (Recommended for Users)

pip install matlab-mcp

This installs the stable released version with all required dependencies.

Option B: From Source (Recommended for Contributors)

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

Use pip install -e ".[dev]" to include development tools (testing, linting, documentation generation).

For monitoring support (health dashboard, metrics), add the monitoring extra:

pip install -e ".[monitoring]"

Option C: Docker (For Isolated Deployments)

Create a Dockerfile or use docker-compose.yml:

# Using docker-compose (edit docker-compose.yml to mount your MATLAB)
docker compose up

# Or build and run manually
docker build -t matlab-mcp:latest .
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 streamablehttp

Docker Requirement: You must mount your own MATLAB installation. The container does not include MATLAB itself (it's a proprietary binary).

Step 3: Create a Configuration File (Optional)

For most users, the defaults work out of the box. But for advanced setups (multi-user, custom security, monitoring), create ~/.matlab_mcp/config.yaml:

# config.yaml - MATLAB MCP Server Configuration

server:
  transport: streamablehttp        # "stdio" (single-user), "sse" (deprecated), or "streamablehttp" (multi-user HTTP)
  host: 127.0.0.1                 # Loopback by default (no firewall issues on Windows)
  port: 8765

pool:
  min_engines: 2                   # Minimum idle engines
  max_engines: 4                   # Maximum total engines
  engine_timeout: 120              # Shutdown idle engines after 120s

execution:
  sync_timeout: 10                 # Inline execution timeout (seconds)
  async_timeout: 300               # Background job timeout (seconds)

security:
  blocked_functions:
    - "system"
    - "eval"
    - "!"
  max_upload_size: 100_000_000     # 100 MB

Or set via environment variables:

export MATLAB_MCP_SERVER_TRANSPORT=streamablehttp
export MATLAB_MCP_SERVER_HOST=0.0.0.0         # For remote access (requires firewall rule)
export MATLAB_MCP_POOL_MAX_ENGINES=8

See Configuration for all options.

Step 4: Run the Server

# Single-user (stdio transport - recommended for local development)
matlab-mcp

# Multi-user HTTP (recommended for teams/clusters)
matlab-mcp --transport streamablehttp

# With custom config
matlab-mcp --config ~/.matlab_mcp/config.yaml

# Generate a bearer token for authentication
matlab-mcp --generate-token

The server will start and display connection information:

[INFO] MATLAB MCP Server starting...
[INFO]   Transport: stdio
[INFO]   MATLAB pool: 1 min, 2 max engines
[INFO]   Health check: http://127.0.0.1:8765/health
[INFO]   Dashboard: http://127.0.0.1:8766/dashboard

Step 5: Connect Your AI Agent

Claude Desktop (macOS / Windows)

  1. Find your Claude config file:

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

  2. Add the server:

{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp"
    }
  }
}
  1. Restart Claude Desktop. The MATLAB tools will appear in the Tools panel.

Cursor

Add to .cursor/mcp.json in your project:

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

Claude Code (Web)

  1. Generate a token:
matlab-mcp --generate-token
# Output: Token: abc123...
#         export MATLAB_MCP_AUTH_TOKEN="abc123..."
  1. Start the server with HTTP transport:
export MATLAB_MCP_AUTH_TOKEN="abc123..."
matlab-mcp --transport streamablehttp
# Output: HTTP endpoint: http://127.0.0.1:8765/mcp
  1. In Claude Code, add server:
    • Name: matlab
    • URL: http://127.0.0.1:8765/mcp
    • Authorization: Bearer abc123...

Codex CLI

Codex CLI requires streamable HTTP transport with bearer token auth:

# Terminal 1: Start server with auth
export MATLAB_MCP_AUTH_TOKEN=$(matlab-mcp --generate-token | grep "Token:" | cut -d' ' -f2)
matlab-mcp --transport streamablehttp

# Terminal 2: Connect Codex CLI
export CODEX_MCP_AUTH_HEADER="Authorization: Bearer $MATLAB_MCP_AUTH_TOKEN"
codex --mcp http://127.0.0.1:8765/mcp

See Agent Onboarding for detailed examples.

Verification

After installation, verify everything works:

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

# Test 2: MCP Server imports
python -c "from matlab_mcp.server import main; print('✓ MCP Server imports OK')"

# Test 3: Start server (Ctrl+C to stop)
matlab-mcp --inspect

# Expected output:
# [INFO] MATLAB MCP Server starting...
# [INFO]   Inspect mode: pool disabled
# [INFO]   Tools: execute_code, get_workspace, list_toolboxes, ...
# Listening on stdio

If you see errors, skip to Troubleshooting.

Installation Methods by Use Case

graph TD A["What's your use case?"] --> B{Single User?} B -->|Yes - Local Dev| C["pip install matlab-mcp
Run: matlab-mcp"] B -->|No - Team/Server| D{Network Access?} D -->|Local Only| E["pip install matlab-mcp
Run: matlab-mcp --transport streamablehttp"] D -->|Remote Access| F["pip install matlab-mcp
Generate token
Configure firewall
Run with --transport streamablehttp"] B -->|Yes - Isolated| G["Docker + docker-compose
Mount MATLAB
Run: docker compose up"]

Troubleshooting

MATLAB Engine API Won't Install

Problem: ERROR: Could not find a version that satisfies the requirement matlab-engine

Solution: The MATLAB Engine API is not on PyPI. Install directly from your MATLAB installation:

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

# Windows (run as your normal user, no admin required)
cd "C:\Program Files\MATLAB\R2024a\extern\engines\python" && pip install .

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

If MATLAB is installed elsewhere, adjust the path.

MATLAB Engine Startup Hangs

Problem: Running matlab.engine.start_matlab() hangs for 30+ seconds.

Cause: MATLAB needs to initialize the JVM and engine. This is normal on first startup.

Solution:

  • Set a timeout: matlab.engine.start_matlab(background=True)
  • Reduce startup time on macOS by disabling certain toolboxes in your MATLAB preferences

"No MATLAB Installation Found"

Problem: Server starts but says "ERROR: No MATLAB installation detected"

Solution: Set the MATLAB root explicitly:

export MATLAB_MCP_POOL_MATLAB_ROOT="/Applications/MATLAB_R2024a.app"  # macOS
export MATLAB_MCP_POOL_MATLAB_ROOT="C:\\Program Files\\MATLAB\\R2024a"  # Windows
matlab-mcp

Connection Refused on Windows 10

Problem: Remote agents can't connect to http://127.0.0.1:8765/mcp

Solution: This is expected for loopback binding (127.0.0.1). For remote access:

  1. Bind to 0.0.0.0:

    export MATLAB_MCP_SERVER_HOST=0.0.0.0
matlab-mcp --transport streamablehttp

  2. Windows Firewall will ask for permission. Click Allow (requires standard user interaction once).

  3. Or add a firewall rule (requires admin):

    netsh advfirewall firewall add rule name="MATLAB MCP" dir=in action=allow program="%ProgramFiles%\Python312\python.exe" enable=yes

"Bearer Token Invalid" on HTTP Transport

Problem: Agents get 401 Unauthorized when connecting to --transport streamablehttp

Solution: Generate and use a bearer token:

# Generate token
TOKEN=$(matlab-mcp --generate-token | grep "Token:" | cut -d' ' -f2)
export MATLAB_MCP_AUTH_TOKEN="$TOKEN"
matlab-mcp --transport streamablehttp

# Client side (e.g., Claude Code)
# Set Authorization header to: Bearer $TOKEN

Docker: "MATLAB not found"

Problem: Docker container starts but MATLAB engine won't initialize

Solution: Mount MATLAB and set the path:

docker run -p 8765:8765 \
  -v /path/to/MATLAB:/opt/matlab:ro \
  -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab \
  matlab-mcp --transport streamablehttp

Replace /path/to/MATLAB with your actual MATLAB installation path:

  • macOS: /Applications/MATLAB_R2024a.app
  • Windows: C:\\Program Files\\MATLAB\\R2024a
  • Linux: /usr/local/MATLAB/R2024a

Still Stuck?

See Troubleshooting or open an issue on GitHub.

Next Steps

  • Configuration: Customize server behavior in config.yaml
  • Custom Tools: Expose your own MATLAB functions via custom_tools.yaml
  • Examples: See ready-to-run MATLAB code in Examples
  • Security: Learn about code validation and authentication in Security
  • Architecture: Deep dive into the Architecture

Clone this wiki locally