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 for best compatibility)
  • MATLAB R2022b+ installed locally (MATLAB Engine API for Python required)
  • Operating Systems: Linux, macOS, or Windows 10+
  • For Windows 10 no-admin deployment: No administrator rights required (the server binds to localhost by default)

Note: The MATLAB Engine API for Python comes bundled with MATLAB but requires a separate installation step. See Step 1 below.

Installation Methods

Option A: PyPI Package (Recommended)

Install the pre-built package from PyPI:

pip install matlab-mcp-python

Verify the installation:

matlab-mcp --help

Option B: From Source (Development)

Clone the repository and install in editable mode:

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

The [dev] extras include:

  • pytest, ruff (testing and code quality)
  • Plotly, aiosqlite (monitoring dashboard)

For minimal install without dev/monitoring:

pip install -e .

For monitoring support only (dashboard, health endpoints):

pip install -e ".[monitoring]"

Option C: Conda Environment

Create and activate a conda environment:

# Create from environment.yml (for users)
conda env create -f environment.yml
conda activate matlab-mcp

# Or create from environment-dev.yml (for developers)
conda env create -f environment-dev.yml
conda activate matlab-mcp-dev

Option D: Docker

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

# Run with MATLAB mounted
docker run -p 8765:8765 \
  -v /path/to/MATLAB:/opt/matlab:ro \
  -v ./config.yaml:/etc/matlab-mcp/config.yaml:ro \
  -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab \
  matlab-mcp

# Or use docker-compose
docker compose up

Important: The Docker image does not include MATLAB. You must mount a local MATLAB installation inside the container, or the server will run in --inspect mode (MATLAB Engine disabled).

Step 1: Install MATLAB Engine API for Python

The MATLAB Engine API is bundled with MATLAB but requires a manual installation into your Python environment.

macOS

Locate your MATLAB installation and install the Engine API:

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

Tip: Replace R2024a with your MATLAB version (e.g., R2023b, R2022b).

Windows

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

For Windows 10 without admin rights: Use the provided install.bat script to automate this process:

.\install.bat

This script detects your Python and MATLAB installations, creates a virtual environment, and installs the Engine API with all necessary workarounds.

Linux

cd /opt/MATLAB/R2024a/extern/engines/python
pip install .

Verify Installation

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

If successful, you should see the message without errors.

Step 2: Install the MCP Server

Follow one of the installation methods above (PyPI, Source, Conda, or Docker).

Step 3: Configure (Optional)

The server uses sensible defaults. To customize, create or edit a config.yaml file:

server:
  host: 127.0.0.1        # Bind to localhost (avoid firewall issues on Windows)
  port: 8765
  transport: stdio       # stdio (single-user) or sse/streamablehttp (multi-user)
  log_level: INFO

pool:
  min_engines: 2
  max_engines: 8
  health_check_interval_s: 5

execution:
  sync_timeout: 30       # Promote to async jobs after 30 seconds

security:
  blocked_functions_enabled: true

monitoring:
  enabled: true          # Enable health/metrics dashboard at /health, /metrics

See Configuration for all available options.

Step 4: Start the Server

Single-User (Default)

matlab-mcp

The server connects to your local MATLAB via stdio. One MCP client (Claude Desktop, Cursor, etc.) can connect at a time.

Multi-User (HTTP/SSE)

matlab-mcp --transport streamablehttp

The server listens on http://127.0.0.1:8765 and supports multiple concurrent clients. Remote agents connect to the /mcp endpoint.

With Authentication (HTTP/SSE Only)

Generate a token:

matlab-mcp --generate-token
# Output: Bearer token: abc123def456...
# Set env var: export MATLAB_MCP_AUTH_TOKEN=abc123def456...

Start the server:

export MATLAB_MCP_AUTH_TOKEN=abc123def456...
matlab-mcp --transport streamablehttp

Agents must include the token in requests:

Authorization: Bearer abc123def456...

With Custom Config

matlab-mcp --config /path/to/config.yaml

Environment variables override config file settings (prefix MATLAB_MCP_):

export MATLAB_MCP_POOL_MIN_ENGINES=4
export MATLAB_MCP_POOL_MAX_ENGINES=16
matlab-mcp

Step 5: Connect Your AI Agent

Claude Desktop

macOS:

mkdir -p "~/Library/Application Support/Claude"
cat > "~/Library/Application Support/Claude/claude_desktop_config.json" << 'EOF'
{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp"
    }
  }
}
EOF

Windows: Create %APPDATA%\Claude\claude_desktop_config.json:

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

Claude Code

claude mcp add matlab -- matlab-mcp

Codex CLI (Streamable HTTP)

# Terminal 1: Start the server
matlab-mcp --transport streamablehttp

# Terminal 2: Connect Codex
codex -m http://127.0.0.1:8765/mcp \
  --bearer-token YOUR_TOKEN_HERE \
  --context matlab

Cursor

Add to .cursor/mcp.json:

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

See Agent Onboarding for detailed configuration examples for each agent.

Verification

Health Check

# If using streamablehttp or sse:
curl http://127.0.0.1:8765/health

# Expected response:
# {
#   "status": "healthy",
#   "uptime_seconds": 45,
#   "engines": {"total": 2, "available": 2, "busy": 0},
#   "active_jobs": 0,
#   "active_sessions": 0
# }

Monitoring Dashboard

Open http://127.0.0.1:8765/dashboard in a browser (if monitoring is enabled and using HTTP transport).

Test with Python

import matlab.engine

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

Troubleshooting

MATLAB Engine API Import Error

Error: ModuleNotFoundError: No module named 'matlab'

Solution:

  1. Verify MATLAB is installed: ls /Applications/MATLAB_*.app (macOS)
  2. Reinstall the Engine API: cd .../extern/engines/python && pip install .
  3. Check Python version: python --version (must be 3.10+)

Port Already in Use

Error: Address already in use: ('127.0.0.1', 8765)

Solution:

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

# Or kill the existing process
lsof -ti:8765 | xargs kill -9  # macOS/Linux
netstat -ano | findstr :8765   # Windows

Windows Firewall Blocking

Error: Agent cannot connect to http://127.0.0.1:8765

Solution:

  • The default bind address is 127.0.0.1 (localhost-only) to avoid firewall popups on Windows 10
  • For remote access, bind to 0.0.0.0 and add a Windows Firewall exception (requires admin): 
    # config.yaml
server:
  host: 0.0.0.0  # Allow remote connections

MATLAB Engine Startup Hangs

Error: Server appears to hang on startup

Solution:

  1. Start with fewer engines: --pool-min-engines 1
  2. Check MATLAB license: Open MATLAB GUI to verify the license is valid
  3. Try inspect mode (no MATLAB): matlab-mcp --inspect

Authentication Token Issues

Error: 401 Unauthorized when connecting agents

Solution:

# Verify token is set
echo $MATLAB_MCP_AUTH_TOKEN

# Generate a new token
matlab-mcp --generate-token

# Export in current shell
export MATLAB_MCP_AUTH_TOKEN="your_token_here"
matlab-mcp --transport streamablehttp

Performance Tuning

For large workloads, adjust configuration:

pool:
  min_engines: 4        # Start with more engines
  max_engines: 16       # Scale up to this many
  health_check_interval_s: 10  # Less frequent checks = lower overhead

execution:
  sync_timeout: 60      # Allow longer sync execution before async promotion

monitoring:
  enabled: false        # Disable metrics collection if CPU-bound

Virtual Environment (Recommended)

# Create isolated Python environment
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

# Install MATLAB Engine API into venv
cd /Applications/MATLAB_R2024a.app/extern/engines/python
pip install .

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

What's Next?

Clone this wiki locally