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 a Python-based bridge that connects any MCP-compatible AI agent (Claude, Cursor, Codex CLI) to a shared MATLAB installation via the Model Context Protocol.

What Does It Do?

The MATLAB MCP Server enables AI agents to:

  • Execute MATLAB code synchronously (fast commands) or asynchronously (long-running jobs with progress tracking)
  • Discover installed toolboxes, functions, and help text without leaving the agent interface
  • Check code quality using MATLAB's built-in checkcode (mlint) linter
  • Generate interactive plots that auto-convert from MATLAB figures to Plotly JSON for display in agents
  • Expose custom MATLAB functions (.m files, MEX binaries, Simulink models) as first-class MCP tools via YAML configuration
  • Manage workspaces and sessions with multi-user isolation, temporary file handling, and automatic cleanup
  • Control resource usage via elastic engine pooling (scale 2–10 MATLAB engines), execution timeouts, and upload size limits

Key Features & Capabilities

  • 🔐 Secure code execution — Function blocklist (system calls, eval, file I/O) with smart string/comment detection
  • ⚡ Elastic pooling — MATLAB engine pool scales dynamically based on demand (2–10 engines configurable)
  • 🔄 Async job system — Code exceeding sync timeout auto-promotes to background jobs with progress reporting via mcp_progress()
  • 📊 Plotly figure conversion — MATLAB plots auto-converted to interactive Plotly JSON + static PNG thumbnails
  • 👥 Multi-user SSE & HTTP — Stateless HTTP (streamable-http) transport with session isolation and bearer token auth
  • 🛠️ Custom tools — Define MATLAB functions as MCP tools in custom_tools.yaml with typed parameters
  • 📡 Monitoring dashboard — Real-time metrics, health checks, event logs, and error tracking via SQLite + Starlette HTTP
  • 🪟 Windows 10 no-admin — Defaults to loopback binding, works without administrator privileges or firewall exceptions
  • 📝 Full-featured CLI — matlab-mcp --help with --inspect (no MATLAB), --generate-token, --transport selection, config override flags

Supported Platforms

Platform MATLAB Version Transports Status
macOS R2022b+ stdio, SSE, HTTP ✅ Production
Linux R2022b+ stdio, SSE, HTTP ✅ Production
Windows 10+ R2022b+ stdio, SSE, HTTP ✅ Production (no-admin default)

Quick Start: 60 Seconds

1. Install

# PyPI (recommended)
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 .

2. Start the Server

# Default: stdio + loopback HTTP (127.0.0.1:8765)
matlab-mcp

# Or with bearer token auth (for remote access)
export MATLAB_MCP_AUTH_TOKEN="$(matlab-mcp --generate-token)"
matlab-mcp --transport streamablehttp

3. Connect an Agent

Claude Code (local):

// ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp"
    }
  }
}

Codex CLI (remote HTTP):

codex --mcp-url http://127.0.0.1:8765/mcp \
      --mcp-auth-header "Authorization: Bearer YOUR_TOKEN"

Cursor (stdio):

  • Go to Settings → Extensions → Codebase Indexing → MCP Server
  • Add: {"name": "matlab", "command": "matlab-mcp"}

4. First Tool Call (in agent)

User: "Run some MATLAB code to plot a sine wave"

Agent calls execute_code:
  code: "x = linspace(0, 2*pi, 100); y = sin(x); plot(x, y); grid on; title('Sine Wave')"
  
Result: {"output": "...", "figures": [{"data": [...], "layout": {...}}]}

Navigation

Page Purpose
Installation Prerequisites, MATLAB Engine API setup, server installation methods
Configuration Complete YAML config reference with all settings and environment variables
Architecture System design: engine pool, job executor, session manager, security, monitoring
MCP Tools Reference All 20 built-in tools with parameters, behavior, and response examples
Custom Tools How to expose MATLAB functions as MCP tools via custom_tools.yaml
Examples Ready-to-run MATLAB examples: plotting, signal processing, async jobs, file I/O
Async Jobs Long-running jobs, automatic promotion, progress tracking, job management
Security Code validation, function blocklist, workspace isolation, upload protection
Troubleshooting Common issues (MATLAB startup, connection, blocklist) with solutions
FAQ Frequent questions: versions, transports, custom tools, performance, testing

Architecture at a Glance

graph TB
    Agent["🤖 AI Agent<br/>(Claude, Cursor, Codex)"]
    
    Transport["📡 Transport Layer<br/>(stdio / SSE / HTTP)"]
    Auth["🔐 Auth Middleware<br/>(Bearer Token)"]
    MCP["🔌 FastMCP Server<br/>(Tool Registration)"]
    
    Session["👤 Session Manager<br/>(Per-user isolation)"]
    Jobs["⚙️ Job System<br/>(Sync → Async Promotion)"]
    Pool["🔄 Engine Pool<br/>(2-10 MATLAB engines)"]
    
    Security["🛡️ Security Validator<br/>(Blocked functions,<br/>path traversal)"]
    Output["📊 Result Formatter<br/>(Text, Variables,<br/>Plotly Conversion)"]
    
    Monitoring["📈 Monitoring<br/>(Metrics, Health,<br/>Dashboard)"]
    
    MATLAB["🔧 MATLAB Engine API<br/>(Code Execution)"]
    
    Agent -->|JSON-RPC| Transport
    Transport --> Auth
    Auth --> MCP
    MCP --> Session
    MCP --> Security
    MCP --> Jobs
    Jobs --> Pool
    Jobs --> Output
    Pool --> MATLAB
    MCP --> Monitoring
    
    style Agent fill:#e1f5ff
    style MATLAB fill:#fff3e0
    style Auth fill:#f3e5f5
    style Security fill:#ffe0b2
    style Monitoring fill:#c8e6c9
Loading

Data Flow: From Agent to MATLAB

sequenceDiagram
    Agent->>Transport: execute_code (code, kwargs)
    Transport->>Auth: Check Authorization header
    Auth->>MCP: ✓ Valid token
    MCP->>Session: Get/create session (workspace isolation)
    MCP->>Security: Validate code (blocklist check)
    Security->>Jobs: ✓ Code safe
    Jobs->>Pool: Acquire MATLAB engine
    Pool->>MATLAB: Execute code (sync or async)
    MATLAB->>Jobs: Return results (output, variables, figures)
    Jobs->>Output: Format results (truncate, convert plots, thumbnails)
    Output->>MCP: Structured response
    MCP->>Transport: JSON-RPC response
    Transport->>Agent: Results displayed in agent UI
Loading

Key Concepts

Sessions & Workspaces

Each agent connection gets an isolated session with its own MATLAB workspace and temporary directory. Sessions auto-expire after inactivity; cleanup is automatic.

Engine Pool

Instead of starting one MATLAB engine per request (slow), the server maintains a pool of 2–10 reusable engines. Engines are acquired on demand, released when idle, and health-checked periodically.

Sync vs. Async Jobs

  • Sync: Code completes within sync_timeout (default 30s) → result returned immediately
  • Async: Code exceeds timeout → promoted to background job, agent can poll for progress

Plotly Conversion

MATLAB figures are extracted to JSON via the mcp_extract_props.m helper, then converted to Plotly-compatible JSON and displayed interactively in agents.

Custom Tools

Define MATLAB functions in custom_tools.yaml (with parameters, types, descriptions) and they appear as first-class MCP tools — agents can discover and call them directly.

Example: Plotting with the Server

% In agent: "Plot a 3D surface of sin(x)*cos(y)"

x = linspace(-pi, pi, 50);
y = linspace(-pi, pi, 50);
[X, Y] = meshgrid(x, y);
Z = sin(X) .* cos(Y);
surf(X, Y, Z);
title('sin(x) * cos(y)');
xlabel('x'); ylabel('y'); zlabel('z');

Result in agent UI: Interactive Plotly 3D surface plot, rotatable and zoomable.

Getting Help

Project Status

v2.0 Released 2026-04-03

All six phases complete:

  • ✅ FastMCP 3.2.0 upgrade with public API routes
  • ✅ Bearer token authentication (YAML + env var config)
  • ✅ Streamable HTTP transport at /mcp endpoint
  • ✅ Human-in-the-loop approval gates for protected operations
  • ✅ Windows 10 no-admin deployment (loopback default, proper temp paths)
  • ✅ Complete documentation and agent onboarding guides

See ROADMAP and Architecture for detailed information.

Clone this wiki locally