Skip to content

Home

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

MATLAB MCP Server

Welcome to the MATLAB MCP Server wiki! This server connects any AI agent to a shared MATLAB installation via the Model Context Protocol (MCP).

What is this?

A Python MCP server that gives AI agents (Claude, Cursor, Copilot, custom agents) the ability to:

  • Execute MATLAB code — sync for fast commands, async for long-running jobs with progress reporting
  • Discover toolboxes & functions — browse installed toolboxes, list functions, retrieve help text
  • Check code quality — run checkcode/mlint linting before execution
  • Generate interactive plots — figures auto-converted to interactive Plotly visualizations
  • Manage files — upload, download, and list session-specific files
  • Monitor performance — track pool utilization, execution metrics, and server health
  • Use custom libraries — expose your own MATLAB functions as first-class MCP tools

Key Features

  • Hybrid sync/async execution — small tasks return instantly; large jobs auto-promote to background with progress tracking
  • Multi-user sessions — isolated workspaces and temp directories per user via SSE transport
  • Engine pool management — dynamic scaling from min to max engines based on demand
  • Security by default — configurable blocklist of dangerous functions, filename sanitization, upload limits
  • Code linting integration — validate code before execution with MATLAB's built-in linter
  • Plotly conversion — all figures automatically converted to interactive JSON format
  • Real-time monitoring — dashboard tracking pool status, execution times, and error rates

Supported Platforms

Platform MATLAB Version Transport
macOS (Intel/Apple Silicon) 2020b+ stdio, SSE
Windows x64 2020b+ stdio, SSE
Linux (MATLAB 2024a+) 2024a+ stdio, SSE

Quick Start

1. Install Prerequisites

macOS / Windows:

# Install MATLAB Engine API for Python
# (from MATLAB: matlabroot/extern/engines/python/)
cd "<YOUR_MATLAB_ROOT>/extern/engines/python"
python -m pip install .

# Or on macOS with Homebrew MATLAB:
python -m pip install matlabengine

Windows (alternative): Run the provided install.bat script—it handles MATLAB detection and setup automatically.

2. Install MCP Server

python -m pip install matlab-mcp-python

3. Start the Server

# Stdio transport (default, for single-user)
matlab-mcp

# SSE transport (for multi-user, with reverse proxy authentication)
matlab-mcp --transport sse --port 8765

4. Connect an Agent

Claude Desktop (~/.config/claude/claude.json on macOS/Linux, or %APPDATA%\Claude\claude.json on Windows):

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

Cursor / VS Code: Install the MCP extension and configure the server endpoint.

5. Hello MATLAB

In your AI agent, try:

Execute this MATLAB code: x = sin(0:0.1:2*pi); plot(x); grid on;

The agent will receive an interactive Plotly chart, execution time, and any errors.

System Architecture Overview

graph LR
    Agent["AI Agent<br/>(Claude, Cursor, etc.)"]
    MCP["FastMCP Server<br/>(stdio or SSE)"]
    JobEx["Job Executor"]
    Pool["Engine Pool<br/>(2-10 MATLAB engines)"]
    Tracker["Job Tracker<br/>(status, history)"]
    Monitor["Metrics Collector<br/>(dashboard, health)"]
    MATLAB["MATLAB Engines<br/>(R2020b+)"]
    
    Agent -->|MCP Protocol| MCP
    MCP -->|submit code| JobEx
    JobEx -->|acquire| Pool
    JobEx -->|track job| Tracker
    Pool -->|execute| MATLAB
    Pool -->|health check| MATLAB
    JobEx -->|record event| Monitor
    Monitor -->|dashboard API| MCP
    MATLAB -->|stdout/stderr| JobEx
Loading

Execution Flow: Sync vs. Async

sequenceDiagram
    participant Agent
    participant Server
    participant Pool as Engine Pool
    participant MATLAB
    
    Agent->>Server: execute_code(code)
    Server->>Tracker: create_job()
    Server->>Pool: acquire_engine()
    Pool->>MATLAB: start background execution
    MATLAB->>MATLAB: (running...)
    
    alt Completes within sync_timeout (30s)
        MATLAB->>Server: result ready
        Server->>Agent: return result (completed)
    else Exceeds sync_timeout
        Server->>Agent: return job_id (pending)
        Agent->>Server: get_job_status(job_id)
        Server->>Agent: progress: 45%, elapsed: 15s
        Note over MATLAB: (still running background)
        MATLAB->>Server: result ready
        Agent->>Server: get_job_result(job_id)
        Server->>Agent: return result (completed)
    end
    
    Pool->>MATLAB: release engine
Loading

Quick Navigation

Page Purpose
Installation Prerequisites, MATLAB Engine API setup, server installation, CLI usage
Configuration All YAML config options (pool, execution, security, monitoring, custom tools)
MCP Tools Reference Reference for all 20 built-in tools with parameters, examples, and responses
Custom Tools Define custom MATLAB functions as MCP tools via YAML configuration
Examples Ready-to-run MATLAB code snippets (basic, plotting, signal processing, async jobs)
Architecture Detailed system design, data flows, engine pool lifecycle, session model
Async Jobs Long-running job execution, progress reporting, job lifecycle and management
Security Function blocklist, workspace isolation, upload protection, SSE auth, recommendations
Troubleshooting Solutions for common issues (engine startup, SSE connections, stuck jobs, etc.)
FAQ Frequently asked questions about versions, agents, deployment, and tuning

Common Tasks

Execute Code Synchronously

Agent: "Calculate sin(π/2) in MATLAB"
Server: Returns result immediately (< 30s)

Run a Long Simulation

Agent: "Run a Monte Carlo simulation with 1 million trials"
Server: Job starts async → agent checks progress → retrieves final result when ready

Upload and Process Data

Agent: "Upload my_data.csv and compute the mean of column 'values'"
Server: File saved to session temp dir → agent calls execute_code → mean is calculated

Plot Results

Agent: "Generate a line plot of y = x^2 for x in [-5, 5]"
Server: Executes plot code → extracts figure → converts to interactive Plotly JSON → agent displays

Discover Functions

Agent: "List functions in the Signal Processing Toolbox"
Server: Runs 'help signal' → returns function list → agent can call get_help on specific functions

Key Concepts

Sessions — Each user/agent gets an isolated session with its own temp directory and workspace.

Engine Pool — A collection of 2–10 MATLAB engines that are reused across jobs for efficiency.

Sync Timeout — Jobs finishing in ≤ 30s (default) return results immediately; slower jobs become async background tasks.

Custom Tools — MATLAB functions you define in custom_tools.yaml become callable MCP tools for agents.

Job Tracking — All jobs (pending, running, completed) are tracked with status, progress, and results.

Plotly Conversion — MATLAB figures are automatically converted to interactive Plotly JSON for agent UIs.

Security Blocklist — Dangerous functions (system, eval, !) are blocked by default; customizable per deployment.

Getting Help

Start here: Installation | Configure: Configuration | Learn tools: MCP Tools Reference

Clone this wiki locally