Skip to content

Installation

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

Installation

The MATLAB MCP Server supports multiple installation methods to fit your workflow and platform.

Prerequisites

  • Python 3.10+ (3.12 recommended for best performance)
  • MATLAB R2022b+ (tested up to R2024b)
  • MATLAB Engine API for Python — included with MATLAB, requires separate Python installation

Platform Notes

  • macOS: Works on Intel and Apple Silicon; max 4 concurrent engines recommended due to known stability limits
  • Windows: Fully supported; batch installer available for one-click setup
  • Linux: Supported if MATLAB is installed; SSE transport recommended for production deployments

Installation Methods

Method 1: PyPI (Recommended)

Install the latest release from Python Package Index:

pip install matlab-mcp-python

Minimal install (core functionality only):

pip install matlab-mcp-python

With monitoring dashboard:

pip install "matlab-mcp-python[monitoring]"

Development install (includes testing & monitoring):

pip install "matlab-mcp-python[dev]"

Method 2: Install from Source

Clone the repository and install in editable mode:

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

# Development (includes all extras + test dependencies)
pip install -e ".[dev]"

Build the distribution wheel:

pip install build
python -m build
# Wheel available in dist/matlab_mcp_python-*.whl

Method 3: Docker

Build and run the containerized server:

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

# Run the container
docker run -p 8765:8765 -p 8766:8766 \
  --mount type=bind,source=/path/to/MATLAB,target=/opt/matlab,readonly \
  -e MATLAB_MCP_POOL_MATLAB_ROOT=/opt/matlab \
  matlab-mcp

# Or use docker-compose (edit docker-compose.yml for your MATLAB path)
docker compose up -d

Important: The Docker image requires you to mount your MATLAB installation. See docker-compose.yml for configuration examples.

Method 4: Windows Batch Installer (No Admin Required)

For Windows users, run the one-click installer:

install.bat

This script:

  • Detects Python 3.10+ installation
  • Auto-discovers MATLAB R2022b+ in standard locations
  • Creates a virtual environment in .\venv
  • Installs the server and MATLAB Engine API from bundled wheels
  • Creates a Start Menu shortcut for easy launching

Prerequisites: Python 3.10+ in your %PATH% and MATLAB installed in a standard location (Program Files, Program Files (x86), or custom registry path).

Step-by-Step Setup

1. Install MATLAB Engine API for Python

The MATLAB Engine API must be installed into your Python environment:

macOS

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

Adjust the version number (e.g., R2023b, R2024b) to match your MATLAB installation.

Windows (PowerShell or Command Prompt)

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

Linux

cd /opt/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.0
eng.quit()

If this succeeds, the MATLAB Engine API is correctly installed.

2. Install the MCP Server

Choose your preferred installation method from Installation Methods above.

3. Verify the Installation

Test that the server can start and load all components:

# Test startup (stdio mode)
matlab-mcp --help

# Should output help text with available options

# Try a dry run (stdio, no actual MATLAB needed for help)
matlab-mcp --version

Or test with a live engine:

# Create a test script
cat > test_mcp.py << 'EOF'
import sys
sys.path.insert(0, '.')
from matlab_mcp.server import create_server

# This will start the server in stdio mode
# Press Ctrl+C to stop
if __name__ == '__main__':
    server = create_server()
    print("Server created successfully!", file=sys.stderr)
EOF

python test_mcp.py

4. Create a Configuration File (Optional)

For custom settings, create a config.yaml:

server:
  transport: stdio
  log_level: info

pool:
  min_engines: 1
  max_engines: 4

execution:
  sync_timeout: 30
  temp_dir: ./temp

security:
  blocked_functions_enabled: true
  max_upload_size_mb: 100

output:
  plotly_conversion: true
  max_inline_text_length: 50000

See Configuration Guide for all available settings.

5. Run the Server

Single-User (stdio transport)

For local development or single-agent use:

matlab-mcp

Or with a custom config:

matlab-mcp --config my_config.yaml

Multi-User (SSE transport)

For production or multi-agent deployments:

matlab-mcp --transport sse --port 8765

The server will listen on http://0.0.0.0:8765/sse by default.

Security: Always run SSE behind a reverse proxy (nginx, Caddy, Traefik) with authentication enabled. See Security for details.

Connect to AI Agents

Claude Desktop

  1. Open your Claude Desktop config file:

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

  2. Add the MATLAB MCP server:

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

Claude Code (CLI)

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

Cursor Editor

Create or edit .cursor/mcp.json:

{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp",
      "args": []
    }
  }
}

SSE Transport (Network Access)

For remote AI agents or multi-user setups:

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

# Connect via: http://<server-ip>:8765/sse

Configure your reverse proxy to forward requests to http://localhost:8765/sse with authentication.

Virtual Environment Setup

Recommended for development and isolated deployments:

# Create virtual environment
python -m venv .venv

# Activate it
source .venv/bin/activate          # macOS/Linux
# or
.venv\Scripts\activate             # Windows PowerShell
# or
.venv\Scripts\activate.bat         # Windows Command Prompt

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

# Install the MCP server
cd /path/to/matlab-mcp-server-python
pip install -e ".[dev]"

# Verify
matlab-mcp --version

Architecture Overview

graph TB
    AI["AI Agent<br/>(Claude, Cursor, etc.)"]
    Transport["MCP Transport<br/>(stdio or SSE)"]
    Server["FastMCP Server<br/>(matlab-mcp)"]
    Pool["Engine Pool Manager<br/>(elastic scaling)"]
    Engines["MATLAB Engines<br/>(2-N instances)"]
    Jobs["Job Tracker<br/>(async management)"]
    Sessions["Session Manager<br/>(workspace isolation)"]
    Config["Configuration<br/>(YAML + env vars)"]
    
    AI <-->|MCP Protocol| Transport
    Transport <--> Server
    Server --> Pool
    Server --> Jobs
    Server --> Sessions
    Server --> Config
    Pool --> Engines
    Jobs --> Engines
    Sessions --> Engines
Loading

Installation Verification Checklist

  • Python 3.10+ installed: python --version
  • MATLAB Engine API working: python -c "import matlab.engine; print('OK')"
  • MCP server installed: matlab-mcp --version
  • Configuration created (if using custom settings)
  • Server starts without errors: matlab-mcp (press Ctrl+C to stop)
  • AI agent can connect and discover tools
  • Test execution: run a simple MATLAB command via the agent

Troubleshooting Installation

"matlab.engine not found"

  • Ensure MATLAB is installed: ls /Applications/MATLAB_R2024a.app (macOS) or check Program Files (Windows)
  • Install the Engine API: navigate to extern/engines/python in your MATLAB installation and run pip install .

"python: command not found"

  • Ensure Python 3.10+ is in your PATH
  • On Windows, run the Python installer and check "Add Python to PATH"

"cannot start MATLAB engine"

  • Verify MATLAB installation: matlab -h should work from terminal
  • Check log output: matlab-mcp --log-level debug

"ModuleNotFoundError: No module named 'fastmcp'"

  • Reinstall dependencies: pip install --upgrade -e ".[dev]"

"Port 8765 already in use" (SSE mode)

  • Use a different port: matlab-mcp --transport sse --port 8766
  • Or kill the existing process: lsof -i :8765 (macOS/Linux) or netstat -ano | findstr :8765 (Windows)

See Troubleshooting for more issues and solutions.

Next Steps

  • Configuration Guide — Customize server behavior, engine pooling, security, output formatting
  • Examples — Run ready-to-use MATLAB examples
  • Custom Tools — Register your own MATLAB functions as MCP tools
  • Security — Multi-layered security architecture and best practices
  • Architecture — Understand how the server works under the hood

Clone this wiki locally