Skip to content

Installation

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

Installation

Prerequisites

Installation Methods

graph TD
    A["Choose Installation Method"] --> B["PyPI<br/>pip install"]
    A --> C["Source<br/>git clone + pip install -e"]
    A --> D["Docker<br/>docker compose"]
    A --> E["Windows One-Click<br/>install.bat<br/>no admin required"]
    
    B --> F["Latest stable release"]
    C --> G["Development version<br/>optional dev extras"]
    D --> H["Containerized deployment<br/>mounted MATLAB"]
    E --> I["Bundled wheels<br/>offline install"]
    
    F --> J["Ready to run<br/>matlab-mcp"]
    G --> J
    H --> J
    I --> J
Loading

Step 1: Install MATLAB Engine API for Python

The MATLAB Engine API is required and comes with your MATLAB installation. Follow the steps below for your platform.

macOS

# Find your MATLAB installation (adjust version as needed)
cd /Applications/MATLAB_R2024a.app/extern/engines/python

# Install into your Python environment
pip install .

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

Windows

# Open Command Prompt and navigate to the Python Engine directory
cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"

# Install
pip install .

Tip: Replace R2024a with your MATLAB version.

Linux

# Adjust path to your MATLAB installation
cd /usr/local/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
eng.quit()

If you see 4, the MATLAB Engine API is correctly installed. If you get an import error, check your MATLAB installation path and ensure Python can access it.

Step 2: Install the MATLAB MCP Server

Choose one of the following methods:

Option A: PyPI (Recommended for Users)

pip install matlab-mcp-python

This installs the latest stable release from PyPI.

Option B: From Source (Recommended for Development)

# Clone the repository
git clone https://github.com/HanSur94/matlab-mcp-server-python.git
cd matlab-mcp-server-python

# Install in editable mode with dev extras
pip install -e ".[dev]"

Optional extras:

  • .[dev] — includes pytest, ruff, coverage (full development environment)
  • .[monitoring] — includes Plotly, monitoring dashboard only (no dev tools)
  • . — minimal install (core only)

Option C: Docker (Multi-Machine Deployments)

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

# Run with mounted MATLAB installation
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

Or use the provided docker-compose.yml:

# Edit docker-compose.yml to set your MATLAB path
docker compose up

Note: Docker images do not include MATLAB. You must mount your own MATLAB R2022b+ installation.

Option D: Windows One-Click Installer (No Admin Rights)

For Windows 10 users without administrator privileges:

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

The script:

  • Auto-detects Python 3.10, 3.11, or 3.12
  • Auto-detects MATLAB R2022b+ installation
  • Creates an isolated virtual environment
  • Installs all dependencies from bundled wheels (fully offline)
  • Works without admin rights

See docs/windows-deployment.md for detailed Windows setup guidance.

Option E: Package Managers

Homebrew (macOS):

brew tap HanSur94/matlab-mcp
brew install matlab-mcp-python

Conda/Mamba:

conda install -c HanSur94 matlab-mcp-python

Verify Installation

# Test the CLI
matlab-mcp --help

# Generate a bearer token (if using HTTP transports)
matlab-mcp --generate-token

# Quick test: run in inspect mode without MATLAB
matlab-mcp --inspect

Configuration

The server reads from config.yaml (optional). If no config exists, defaults are used.

Create a minimal config:

server:
  transport: stdio  # or "sse" for multi-user, "streamablehttp" for agents
  host: 127.0.0.1
  port: 8765

pool:
  min_engines: 2
  max_engines: 10

Override any setting via environment variables:

MATLAB_MCP_SERVER_TRANSPORT=sse matlab-mcp
MATLAB_MCP_POOL_MAX_ENGINES=20 matlab-mcp

For complete configuration reference, see wiki/Configuration.md.

Connect to AI Agents

Claude Desktop

  1. Open your Claude Desktop config:

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

  2. Add the server entry:

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

Claude Code

# If matlab-mcp is in your PATH
claude mcp add matlab -- matlab-mcp

# Or specify the full path
claude mcp add matlab -- /path/to/matlab-mcp

Then use the MATLAB tools in Claude Code's chat interface.

Cursor

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

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

Restart Cursor and the MATLAB tools will be available.

Codex CLI (Streamable HTTP + Bearer Token)

Start the server with streamable HTTP transport:

# Generate a token
export MATLAB_MCP_AUTH_TOKEN=$(matlab-mcp --generate-token | grep "Token:" | awk '{print $NF}')

# Start the server
matlab-mcp --transport streamablehttp

Connect Codex CLI:

codex-cli connect http://127.0.0.1:8765/mcp \
  --auth-header "Authorization: Bearer $MATLAB_MCP_AUTH_TOKEN"

For more agent connection examples, see docs/agent-onboarding.md.

Using a Virtual Environment (Recommended)

Isolate dependencies in a virtual environment:

# Create environment
python -m venv .venv

# Activate
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
cd /path/to/matlab-mcp-server-python
pip install -e ".[dev]"

Troubleshooting

MATLAB Engine API not found

ImportError: No module named 'matlab.engine'

Solution:

  1. Confirm MATLAB is installed: which matlab or where matlab (Windows)
  2. Verify Engine API installation path exists
  3. Try installing again: cd /Applications/MATLAB_R2024a.app/extern/engines/python && pip install .

matlab-mcp command not found

Solution:

  • If using a virtual environment, ensure it's activated
  • If installing from source, use pip install -e . (with the .)
  • Check that the installation succeeded: pip show matlab-mcp-python

Port 8765 already in use

Solution:

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

Or set in config.yaml:

server:
  host: 127.0.0.1
  port: 8766

Connection refused (SSE/HTTP transport)

Solution:

  1. Check the server is running: matlab-mcp --transport sse
  2. Verify the port is accessible: curl http://127.0.0.1:8765/health
  3. On Windows, check Windows Firewall hasn't blocked the port (use 0.0.0.0 binding or add firewall exemption)

MATLAB Engine hangs on startup

Solution:

  • On Windows with network drives, try disabling network path caching: 
    matlab-mcp --config config.yaml
    And set in config.yaml: 
    pool:
  matlab_root: "C:\\Program Files\\MATLAB\\R2024a"

Windows: need admin rights to open firewall

Solution: The default binding is 127.0.0.1 (loopback), which doesn't require admin. If you need remote access:

  1. Run as admin once to add firewall rule
  2. Or ask your IT department to add an exemption for port 8765
  3. See docs/windows-deployment.md for full guidance

Next Steps

For issues or questions, open a GitHub issue or check the FAQ.

Clone this wiki locally