Skip to content

Home

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

MATLAB MCP Server — Home

Welcome to the MATLAB MCP Server wiki! This is your complete guide to connecting any AI agent to MATLAB through the Model Context Protocol (MCP).

What is this?

A Python MCP server that gives AI agents (Claude, Cursor, Codex CLI, and others) the ability to:

  • Execute MATLAB code — sync for fast commands, async for long-running jobs (hours!)
  • Discover toolboxes & functions — browse installed toolboxes, list functions, read help text
  • Check code quality — run MATLAB's checkcode/mlint before execution
  • Get interactive plots — figures auto-convert to Plotly JSON for rendering in web UIs
  • Manage files — upload data, read scripts, retrieve results from session directories
  • Use custom libraries — expose your .m or .mex functions as first-class AI tools
  • Monitor server health — real-time metrics, engine pool status, error logs

Key Features

  • 🔄 Elastic engine pooling — scales 2-10+ MATLAB engines based on demand
  • 👥 Multi-user isolation — sessions with dedicated workspaces and temp directories
  • 📊 Plotly figure conversion — MATLAB plots → interactive JSON (line, bar, scatter, 3D, subplots, heatmaps)
  • ⏱️ Async job promotion — long-running code auto-executes in background; agent keeps working
  • 🎯 Custom tools — define .m functions in YAML; AI agents discover and call them
  • 📈 Progress reporting — long jobs report percentage back to the agent via mcp_progress()
  • 🔐 Security layers — blocked functions list, workspace reset between jobs, filename validation
  • 💻 Cross-platform — Windows 10+ (no admin), macOS (MATLAB R2022b+)
  • ⚡ One-click Windows install — offline install.bat with bundled wheels

System Architecture

graph TB
    Agent["🤖 AI Agent<br/>(Claude, Cursor, Codex CLI)"]
    
    subgraph Transport["🔗 Transport Layer"]
        stdio["stdio<br/>(single-user)"]
        sse["SSE<br/>(multi-user, deprecated)"]
        http["HTTP Streamable<br/>(multi-user, new)"]
    end
    
    subgraph Server["🖥️ MCP Server"]
        auth["Auth Middleware<br/>(bearer token)"]
        tools["Tool Handlers<br/>(execute, discover, files, jobs)"]
    end
    
    subgraph Engine["⚙️ Engine Layer"]
        pool["Engine Pool Manager<br/>(elastic scaling 2-10+)"]
        health["Health Checker<br/>(periodic restart)"]
    end
    
    subgraph Execution["🔨 Job Execution"]
        executor["JobExecutor<br/>(sync + async promo)"]
        jobs["JobTracker<br/>(job registry)"]
        session["SessionManager<br/>(workspace isolation)"]
    end
    
    subgraph Safety["🛡️ Security & Output"]
        validator["SecurityValidator<br/>(code blocking)"]
        formatter["ResultFormatter<br/>(text, variables, plots)"]
        plotly["Plotly Converter<br/>(MATLAB → JSON)"]
    end
    
    subgraph Monitoring["📊 Monitoring"]
        collector["MetricsCollector<br/>(counters, timings)"]
        store["MetricsStore<br/>(SQLite persistence)"]
        dashboard["Dashboard<br/>(HTTP + SSE UI)"]
    end
    
    MATLAB["🔧 MATLAB Engine API<br/>(R2022b+)"]
    
    Agent -->|calls tools| Transport
    Transport --> auth
    auth --> tools
    tools --> executor
    executor --> pool
    executor --> validator
    executor --> session
    executor --> formatter
    formatter --> plotly
    pool --> MATLAB
    pool --> health
    executor --> jobs
    jobs --> collector
    collector --> store
    store --> dashboard
Loading

Quick Start

Prerequisites

# Install MATLAB Engine API (from your MATLAB installation directory)
cd /Applications/MATLAB_R2024a.app/extern/engines/python  # macOS
# cd "C:\Program Files\MATLAB\R2024a\extern\engines\python"  # Windows
pip install .

Install the Server

Option 1: Windows (One-Click Installer)

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

The installer auto-detects MATLAB, creates a virtual environment, installs from bundled wheels — no internet required, no admin rights needed.

Option 2: PyPI (Any Platform)

pip install matlab-mcp-python

Option 3: From Source

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

Run the Server

# Single user (local, no network)
matlab-mcp

# Multi-user over HTTP (requires bearer token)
matlab-mcp --transport streamablehttp --generate-token

When you run --generate-token, it outputs a 64-character hex token and environment variable snippets for every platform:

Token: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0

POSIX (bash/zsh):
  export MATLAB_MCP_AUTH_TOKEN="a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0"

Windows cmd:
  set MATLAB_MCP_AUTH_TOKEN=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0

Windows PowerShell:
  $env:MATLAB_MCP_AUTH_TOKEN = "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0"

Connect an AI Agent

Claude Desktop (stdio transport):

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Claude Code (HTTP transport with token):

claude mcp add matlab http://127.0.0.1:8765/mcp \
  --header "Authorization: Bearer a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0"

Codex CLI (HTTP transport with token):

codex mcp add matlab \
  --transport streamable-http \
  --url http://127.0.0.1:8765/mcp \
  --header "Authorization: Bearer a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0"

Cursor (HTTP transport with token):

Create .cursor/mcp.json:

{
  "mcpServers": {
    "matlab": {
      "command": "python",
      "args": ["-m", "matlab_mcp.server", "--transport", "streamablehttp"],
      "env": {
        "MATLAB_MCP_AUTH_TOKEN": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0"
      }
    }
  }
}

Hello World

Once connected, ask your agent:

Compute the eigenvalues of [1 2; 3 4] and plot them in the complex plane.

The agent will call:

A = [1 2; 3 4];
evals = eig(A);
scatter(real(evals), imag(evals), 100, 'filled');
xlabel('Real'); ylabel('Imaginary');
title('Eigenvalues');

You'll get back an interactive Plotly chart showing the two eigenvalues plotted.

Wiki Navigation

Topic Purpose
Installation Step-by-step setup, MATLAB Engine API, Windows/macOS specifics
Configuration All config.yaml options with descriptions and examples
MCP-Tools-Reference Complete tool catalog (20 tools), parameters, return values, examples
Custom-Tools How to expose your .m functions as discoverable AI tools
Examples Ready-to-run code snippets (matrix operations, plotting, signal processing)
Architecture System design: layers, component responsibilities, data flows
Async-Jobs Long-running jobs, mcp_progress(), job lifecycle, cancellation
Security Code blocklist, workspace isolation, file upload limits, threat model
Troubleshooting Solutions for common problems (engine startup, SSE, plots, etc.)
FAQ Common questions: versions, Docker, performance, custom functions

Common Tasks

Run MATLAB code and get results

See MCP-Tools-Reference#execute_code — agent calls execute_code with MATLAB code; you get stdout, variables, and plots.

Long simulation taking hours?

See Async-Jobs — code auto-promotes to background execution; agent polls status with get_job_status while MATLAB computes.

Add a custom MATLAB function

See Custom-Tools — define a .m file, list it in config.yaml, and the agent can call it like a built-in tool.

See server health and metrics

See Architecture#Monitoring-Layer — access the monitoring dashboard at http://localhost:8766 to view engine pool status, job throughput, error rates.

Secure the server for production

See Security — bearer token auth, workspace isolation, blocked functions list, and reverse-proxy setup guidance.

Support

Last Updated: April 2026 | Version: 2.0.0 | License: MIT

Clone this wiki locally