Skip to content

Home

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

Home

Welcome to the MATLAB MCP Server wiki! This server connects AI agents to MATLAB via the Model Context Protocol (MCP), enabling code execution, toolbox discovery, code checking, interactive plotting, and custom tool exposure.

What This Server Does

The MATLAB MCP Server is a Python application that bridges AI agents (Claude, Cursor, Copilot, and other MCP clients) to a shared or local MATLAB installation. It provides a safe, scalable interface for agents to:

  • Execute MATLAB code — synchronously for quick commands or asynchronously for long-running jobs
  • Discover toolboxes and functions — browse installed MATLAB toolboxes and retrieve help documentation
  • Check code quality — lint MATLAB code using checkcode/mlint before execution
  • Visualize data interactively — automatically convert MATLAB figures to Plotly JSON for agent UI rendering
  • Expose custom libraries — register your own .m functions as first-class MCP tools discoverable by agents
  • Manage files and data — upload, download, and list files within isolated session directories
  • Monitor system health — track engine pool utilization, job metrics, and execution statistics

Key Features

  • Elastic Engine Pool — Automatically scales from min_engines to max_engines based on demand; idles engines scale down to conserve resources
  • Automatic Async Promotion — Code exceeding sync_timeout is promoted to background jobs with progress reporting
  • Session Isolation — Each client maintains a dedicated temp directory and workspace; sessions auto-cleanup on idle timeout
  • Security by Default — Blocked function list (system, eval, etc.) prevents dangerous operations; upload limits and filename sanitization prevent abuse
  • Code Checking — Optional auto-linting before execution; all code quality issues reported to the agent
  • Figure Conversion — MATLAB plots automatically converted to interactive Plotly visualizations
  • Custom Tools — Expose domain-specific MATLAB functions via custom_tools.yaml; agents discover and invoke them like native MCP tools
  • Real-time Monitoring — Built-in dashboard tracks pool utilization, job stats, error logs, and system metrics
  • Cross-platform Support — Windows, macOS, and Docker; works with stdio (single-user) or SSE (multi-user) transports

Supported Platforms & Languages

Platform MATLAB Version Python Transport
Windows 2020b+ 3.10–3.12 stdio, SSE
macOS 2020b+ 3.10–3.12 stdio, SSE
Linux 2020b+ 3.10–3.12 stdio, SSE (with Docker)

Languages: JavaScript (dashboard), Python (server + tools), MATLAB/Objective-C (engine)

Quick Start

1. Install

Windows:

install.bat

macOS/Linux:

pip install matlab-mcp-server
python -m matlab_mcp.server

Docker:

docker-compose up

2. Hello, MATLAB!

# The simplest use case: execute MATLAB code
# (Normally an AI agent would call this via MCP)

code = """
x = [1, 2, 3];
y = x .* 2;
disp(y)
"""

# Result: ans = 2 4 6

3. Connect to an AI Agent

Update your Claude Desktop config:

{
  "mcpServers": {
    "matlab": {
      "command": "python",
      "args": ["-m", "matlab_mcp.server"]
    }
  }
}

Tell Claude: "Use the matlab tool to solve my problem..."

Documentation

graph TD
    A["📚 Documentation"] --> B["Getting Started"]
    A --> C["Configuration & Deployment"]
    A --> D["Reference & Examples"]
    A --> E["Advanced Topics"]
    
    B --> B1["[[Installation]] <br/> Setup, MATLAB Engine API, prerequisites"]
    B --> B2["[[Quick Start Example]]"]
    
    C --> C1["[[Configuration]] <br/> YAML reference, environment vars"]
    C --> C2["[[Security]] <br/> Blocklist, isolation, authentication"]
    
    D --> D1["[[MCP Tools Reference]] <br/> All 20 built-in tools"]
    D --> D2["[[Custom Tools]] <br/> Expose .m functions"]
    D --> D3["[[Examples]] <br/> Common MATLAB patterns"]
    
    E --> E1["[[Architecture]] <br/> System design, engine pool, async"]
    E --> E2["[[Async Jobs]] <br/> Long-running code, progress"]
    E --> E3["[[Troubleshooting]] <br/> Common issues & fixes"]
    E --> E4["[[FAQ]] <br/> Q&A"]
    
    style A fill:#0078d4,stroke:#005a9e,color:#fff
    style B fill:#50e6ff,stroke:#005a9e,color:#000
    style C fill:#50e6ff,stroke:#005a9e,color:#000
    style D fill:#50e6ff,stroke:#005a9e,color:#000
    style E fill:#50e6ff,stroke:#005a9e,color:#000
Loading

System Architecture

graph LR
    Agent["🤖 AI Agent<br/>Claude, Cursor, etc."]
    
    subgraph "MATLAB MCP Server"
        MCP["FastMCP Router<br/>20+ Tools"]
        Security["🔒 Security Validator<br/>Blocked functions, uploads"]
        Executor["⚙️ Job Executor<br/>Sync/Async promotion"]
        Pool["🔵 Engine Pool Manager<br/>Min/max engines, scaling"]
        Sessions["👤 Session Manager<br/>Temp dirs, cleanup"]
        Monitoring["📊 Metrics Collector<br/>Health, utilization"]
    end
    
    Engines["🔧 MATLAB Engines<br/>Workspace, eval()"]
    Dashboard["📈 Dashboard<br/>http://localhost:8766"]
    
    Agent -->|MCP| MCP
    MCP --> Security
    Security --> Executor
    Executor --> Pool
    Pool --> Engines
    Pool --> Sessions
    Pool --> Monitoring
    Monitoring --> Dashboard
    
    style Agent fill:#4a90e2,stroke:#2e5c8a,color:#fff
    style MCP fill:#50c878,stroke:#2d7a4a,color:#fff
    style Security fill:#ff6b6b,stroke:#cc5555,color:#fff
    style Executor fill:#ffa500,stroke:#cc8400,color:#fff
    style Pool fill:#9b59b6,stroke:#7d46a0,color:#fff
    style Sessions fill:#1abc9c,stroke:#159878,color:#fff
    style Monitoring fill:#f39c12,stroke:#c27f0e,color:#fff
    style Engines fill:#34495e,stroke:#2c3e50,color:#fff
    style Dashboard fill:#ecf0f1,stroke:#95a5a6,color:#000
Loading

Data Flow: Code Execution

sequenceDiagram
    participant Agent
    participant MCP as FastMCP
    participant Security
    participant Executor
    participant Pool
    participant Engine as MATLAB Engine
    
    Agent->>MCP: execute_code(code)
    MCP->>Security: validate(code)
    Security-->>MCP: ✓ or BlockedFunctionError
    MCP->>Executor: execute(session_id, code)
    Executor->>Pool: acquire()
    Pool-->>Executor: engine
    Executor->>Engine: eval(code, background=sync_timeout < duration)
    alt Sync (< 30s)
        Engine-->>Executor: result
        Executor-->>MCP: {status: completed, output}
    else Async (>= 30s)
        Engine-->>Executor: job_id
        Executor-->>MCP: {status: running, job_id}
        Engine->>Engine: background execution
        Agent->>MCP: get_job_status(job_id)
        MCP->>Executor: query_job(job_id)
        Executor-->>MCP: {status, progress, elapsed}
    end
    Executor->>Pool: release(engine)
    MCP-->>Agent: result
Loading

Navigation

Section Purpose
Installation Prerequisites, MATLAB Engine API setup, server installation
Configuration Full YAML reference, environment overrides, path resolution
MCP Tools Reference All 20 built-in tools with parameters, behavior, and examples
Custom Tools Define and expose custom .m functions as MCP tools
Examples Ready-to-run MATLAB code patterns, plotting, signal processing
Architecture System design, component responsibilities, data flow diagrams
Async Jobs Job lifecycle, progress reporting, timeout handling
Security Blocklist, workspace isolation, upload limits, proxy auth
Troubleshooting Common issues, debug steps, platform-specific solutions
FAQ Setup, usage, performance, security Q&A

Quick Links

Example: Running a Simulation

Suppose you want to ask Claude to run a Monte Carlo simulation:

% Agent: "Run a Monte Carlo simulation to estimate pi"

n = 1000000;
x = rand(n, 1);
y = rand(n, 1);
distances = sqrt(x.^2 + y.^2);
inside = sum(distances <= 1);
pi_estimate = 4 * inside / n;

disp(['Pi estimate: ', num2str(pi_estimate)]);

The server will:

  1. ✅ Validate the code (no blocked functions)
  2. 🚀 Detect it exceeds sync_timeout → promote to async job
  3. 📊 Return job_id to the agent
  4. ⏳ Agent polls get_job_status(job_id) for progress
  5. ✓ When done, agent calls get_job_result(job_id) for the answer

No configuration needed—it all happens automatically!

Welcome! Start with Installation, then explore Examples to see what's possible.

Clone this wiki locally