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 AI coding agents (Claude, Cursor, Copilot, and any MCP-compatible client) to a shared MATLAB installation via the Model Context Protocol (MCP).

What Does This Server Do?

The MATLAB MCP Server enables AI agents to:

  • Execute MATLAB code — synchronously for quick commands, asynchronously for long-running computations
  • Discover MATLAB resources — browse installed toolboxes, list available functions, retrieve help text
  • Validate code quality — run MATLAB's checkcode linter before execution to catch bugs early
  • Work with interactive plots — MATLAB figures automatically convert to interactive Plotly JSON visualizations
  • Extend functionality — expose custom MATLAB functions (.m files) as first-class MCP tools without code changes
  • Manage files — upload data files (.mat, .xlsx, .csv), download results, and read MATLAB scripts
  • Monitor execution — track long-running jobs, report progress, view server health and metrics

Why This Project Exists

MATLAB is powerful for numerical computing, signal processing, and domain-specific toolboxes, but it's isolated from modern AI workflows. This server bridges that gap, allowing agents like Claude Code and Codex CLI to leverage MATLAB's capabilities directly in their conversations and automations. Setup is minimal: install the server, set an auth token, and any MCP-compatible agent can connect.

Key Features

graph LR
    Agent["🤖 AI Agent<br/>(Claude, Cursor, etc)"]
    Transport["📡 Transport<br/>(stdio/HTTP)"]
    Auth["🔐 Bearer Token<br/>Authentication"]
    Tools["🛠️ MCP Tools<br/>(20+ built-in)"]
    Exec["⚙️ Execution<br/>(Sync/Async)"]
    Pool["🔄 Engine Pool<br/>(Multi-instance)"]
    MATLAB["🧮 MATLAB<br/>R2020b+"]
    
    Agent -->|MCP Protocol| Transport
    Transport -->|Validates| Auth
    Auth -->|Calls| Tools
    Tools -->|Uses| Exec
    Exec -->|Acquires| Pool
    Pool -->|Runs Code| MATLAB
Loading

Core Capabilities

  • ✅ Synchronous execution — Fast MATLAB commands complete within 10 seconds (configurable)
  • ✅ Asynchronous jobs — Long-running tasks auto-promote to background jobs with progress tracking
  • ✅ Per-session isolation — Each agent connection gets its own workspace directory
  • ✅ Multi-engine scaling — Configurable engine pool (1–16 instances) for concurrent execution
  • ✅ Security validation — Blocklist of dangerous functions (e.g., system(), eval()) with smart string literal detection
  • ✅ Bearer token auth — Simple environment variable configuration, no OAuth complexity
  • ✅ Custom tools — Define MATLAB functions as MCP tools via YAML, no Python code needed
  • ✅ Interactive plots — MATLAB figures convert to Plotly JSON automatically
  • ✅ Monitoring dashboard — Real-time metrics, health status, execution logs
  • ✅ Windows 10 no-admin — Runs on restricted machines without elevation
  • ✅ Cross-platform — Linux, macOS, Windows with matching behavior

Quick Start

1. Install

Prerequisites: Python 3.10+, MATLAB R2020b+ with Engine API

# Install from PyPI
pip install matlab-mcp

# Or from source
git clone https://github.com/HanSur94/matlab-mcp-server-python
cd matlab-mcp-server-python
pip install -e .

2. Generate Auth Token

matlab-mcp --generate-token
# Output:
# Token:        a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
# 
# POSIX/Linux:
# export MATLAB_MCP_AUTH_TOKEN=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
#
# Windows (Command Prompt):
# set MATLAB_MCP_AUTH_TOKEN=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
#
# Windows (PowerShell):
# $env:MATLAB_MCP_AUTH_TOKEN="a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"

3. Start the Server

# Set auth token (copy the line from step 2)
export MATLAB_MCP_AUTH_TOKEN=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

# Start the server (stdio transport for local use)
matlab-mcp --transport stdio

# Or start on HTTP for remote agents
matlab-mcp --transport streamablehttp --host 127.0.0.1 --port 8765

4. Connect an Agent

Claude Code:

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

Codex CLI (remote):

export MATLAB_MCP_AUTH_TOKEN=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
codex connect http://127.0.0.1:8765/mcp \
  --header "Authorization: Bearer $MATLAB_MCP_AUTH_TOKEN"

5. First Command

In your agent (Claude, Cursor, etc.), ask:

"Execute this MATLAB code: A = [1 2; 3 4]; det(A)"

Expected response:

Job ID: job_abc123
Output: -2
Status: COMPLETED

Supported Platforms

Platform MATLAB Version Python Transport Support
macOS (Intel/ARM) R2020b+ 3.10–3.12 stdio, streamable HTTP
Windows 10+ R2020b+ 3.10–3.12 stdio, streamable HTTP
Linux (Ubuntu 20.04+) R2020b+ 3.10–3.12 stdio, streamable HTTP

Architecture Overview

The server is organized into layers:

graph TB
    subgraph "Transport Layer"
        Stdio["stdio (single-user)"]
        HTTP["streamable HTTP (multi-user)"]
    end
    subgraph "Authentication"
        Auth["Bearer Token Middleware<br/>(MATLAB_MCP_AUTH_TOKEN)"]
    end
    subgraph "MCP Layer"
        Tools["20+ MCP Tools<br/>(execute_code, upload_data, etc)"]
    end
    subgraph "Execution Engine"
        Exec["Job Executor"]
        Tracker["Job Tracker"]
        Session["Session Manager"]
    end
    subgraph "Resource Pool"
        Pool["MATLAB Engine Pool<br/>(1–16 instances)"]
    end
    subgraph "Security"
        Validator["Code Validator<br/>(blocklist, sanitization)"]
    end
    subgraph "Monitoring"
        Metrics["Metrics Collector"]
        Dashboard["Live Dashboard"]
    end
    
    Stdio --> Auth
    HTTP --> Auth
    Auth --> Tools
    Tools --> Exec
    Exec --> Session
    Exec --> Pool
    Exec --> Validator
    Tracker --> Metrics
    Metrics --> Dashboard
    
    style Stdio fill:#e1f5ff
    style HTTP fill:#e1f5ff
    style Auth fill:#fff3e0
    style Tools fill:#f3e5f5
    style Exec fill:#e8f5e9
    style Pool fill:#fce4ec
    style Dashboard fill:#f1f8e9
Loading

Key components:

  1. Transport Layer — stdio for local single-user, streamable HTTP for remote agents
  2. Authentication — Bearer tokens from MATLAB_MCP_AUTH_TOKEN env var, validated per request
  3. MCP Tools — 20+ tools implementing code execution, discovery, file management, job tracking
  4. Execution Engine — Coordinates job lifecycle, session isolation, workspace cleanup
  5. Engine Pool — Dynamically scales 1–16 MATLAB instances based on demand
  6. Security Validator — Blocks dangerous functions, sanitizes filenames, validates code
  7. Monitoring — Real-time metrics, SQLite persistence, live HTML dashboard

Documentation Navigation

graph LR
    Home["📖 Home<br/>(this page)"]
    
    Setup["🚀 Setup"]
    Install["Installation"]
    Config["Configuration"]
    Windows["Windows Deployment"]
    AgentOnboarding["Agent Onboarding"]
    
    Reference["📚 Reference"]
    Tools["MCP Tools Reference"]
    CustomTools["Custom Tools"]
    Examples["Examples"]
    
    Advanced["🔧 Advanced"]
    Architecture["Architecture"]
    AsyncJobs["Async Jobs"]
    Security["Security"]
    Troubleshooting["Troubleshooting"]
    FAQ["FAQ"]
    
    Home --> Install
    Home --> Config
    Home --> Tools
    Home --> Examples
    
    Install -.-> Windows
    Install -.-> AgentOnboarding
    
    Config -.-> CustomTools
    Config -.-> Security
    
    Tools -.-> Troubleshooting
    
    Examples -.-> AsyncJobs
    
    Architecture -.-> FAQ
Loading

Suggested reading order:

  1. Installation — Get the server running
  2. Configuration — Customize for your setup
  3. Agent-Onboarding — Connect Claude Code, Cursor, Codex CLI
  4. MCP-Tools-Reference — Explore available tools
  5. Examples — Copy/paste working code snippets
  6. Architecture — Understand the design
  7. Troubleshooting — Fix common issues

Frequently Asked Questions

Q: Does this work with Codex CLI?
A: Yes! Codex CLI requires streamable HTTP transport. Use --transport streamablehttp and pass the auth token via HTTP header.

Q: Can multiple agents connect simultaneously?
A: Yes. Use the streamablehttp transport and configure the engine pool size in config.yaml (default is 4 instances).

Q: What if MATLAB takes longer than 10 seconds?
A: Commands are automatically promoted to async background jobs. Use the get_job_status and get_job_result tools to check progress.

Q: Can I add my own MATLAB functions?
A: Yes. Create a custom_tools.yaml file and define your functions there. See Custom-Tools for details.

Q: Is this secure for shared/corporate use?
A: Yes. The server includes per-function blocklists, workspace isolation per session, and bearer token auth. See Security for details.

Q: Does this work on Windows without admin rights?
A: Yes, with the right config. See Windows-Deployment for setup instructions.

Support & Contributing

Version Info

Current Version: v2.0.0 (released 2026-04-03)

Key Features in v2.0:

  • FastMCP 3.2.0 with public APIs
  • Bearer token authentication
  • Streamable HTTP transport (SSE deprecated)
  • Human-in-the-loop approval gates
  • Windows 10 no-admin support
  • Comprehensive documentation

Changelog: See Release Notes or GitHub Releases

Last updated: April 3, 2026
Status: Stable (v2.0 GA)

Clone this wiki locally