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 server bridges AI coding agents (Claude, Cursor, Copilot, and MCP-compatible CLIs) to MATLAB execution environments via the Model Context Protocol (MCP).

What This Project Does

The MATLAB MCP Server is a Python-based bridge that enables any MCP-compatible AI agent to securely execute MATLAB code, discover toolboxes and functions, check code quality, generate interactive Plotly visualizations, and call custom MATLAB libraries—all without leaving the agent's interface.

Core value: Any coding agent connects with minimal setup (one environment variable for auth) and gets native access to MATLAB execution, eliminating context-switching friction for teams that rely on MATLAB.

Key Features

  • Code Execution — Synchronous for quick commands, automatic async promotion for long-running jobs
  • Elastic Engine Pool — Scales from min_engines to max_engines under load; health checks replace failed engines
  • Workspace & Session Isolation — Per-user sessions with dedicated temp directories; workspace reset between executions
  • Async Job System — Long-running jobs auto-promoted on timeout; progress reporting via mcp_progress() helper
  • Security Validation — Configurable function blocklist (system, eval, etc.), filename sanitization, upload size limits
  • Toolbox Discovery — Browse installed MATLAB toolboxes, search functions, fetch help text
  • Code Quality Checks — Run checkcode linting before execution
  • Figure-to-Plotly Conversion — MATLAB plots auto-converted to interactive Plotly JSON + static PNG/SVG
  • Custom Tools — Expose your own .m and .mex functions as first-class AI-callable MCP tools via YAML config
  • Multi-User HTTP Transport — SSE (deprecated) or streamable HTTP for team deployments with per-session isolation
  • Monitoring Dashboard — Real-time metrics: pool utilization, job throughput, error rates, execution time percentiles
  • Bearer Token Authentication — Static token auth via MATLAB_MCP_AUTH_TOKEN env var; no OAuth complexity
  • Human-in-the-Loop Approval Gates — Optional approval prompts for protected functions and file operations

Supported Platforms & Versions

Platform MATLAB Version Python Transport
macOS R2022b+ 3.10+ stdio, SSE, streamable HTTP
Windows R2022b+ 3.10+ stdio, SSE, streamable HTTP
Linux R2022b+ 3.10+ stdio, SSE, streamable HTTP
Docker R2022b+ 3.10+ stdio, SSE, streamable HTTP

Note: macOS has a 4-engine limit built into MATLAB. The server respects this ceiling automatically.

Quick Start

Installation

# Via PyPI
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 .

Hello World

# Generate a 64-character bearer token
export MATLAB_MCP_AUTH_TOKEN=$(python -c "import secrets; print(secrets.token_hex(32))")

# Start the server (stdio transport, single agent)
matlab-mcp --transport stdio

# In another terminal, test with a simple agent command
# (for real usage, configure Claude Desktop, Cursor, or Codex CLI)

For Teams (Streamable HTTP)

# Config file: config.yaml
server:
  transport: streamablehttp
  host: 127.0.0.1  # Avoid Windows Firewall prompts
  port: 8765

sessions:
  max_sessions: 50
  session_timeout: 3600

# Start with auth
export MATLAB_MCP_AUTH_TOKEN=$(python -c "import secrets; print(secrets.token_hex(32))")
matlab-mcp --config config.yaml

# Agents connect via:
# Authorization: Bearer $MATLAB_MCP_AUTH_TOKEN
# POST http://localhost:8765/mcp

With Custom MATLAB Tools

# custom_tools.yaml
tools:
  - name: "fft_analysis"
    description: "Perform FFT on input signal"
    function: "signal_processing.fft_analysis"
    parameters:
      - name: signal
        type: array
        description: "Input signal array"
      - name: sample_rate
        type: float
        description: "Sample rate in Hz"

# In config.yaml:
custom_tools:
  config_file: ./custom_tools.yaml

# Start the server
matlab-mcp

See Examples for more runnable MATLAB code samples.

Navigation

Getting Started

  • Installation — Prerequisites, MATLAB Engine API setup, PyPI/source/Docker installation
  • Windows-Deployment — No-admin installation and configuration for Windows 10

Configuration & Usage

  • Configuration — All YAML config options with environment variable overrides
  • MCP-Tools-Reference — Complete catalog of 20 built-in tools with parameters and JSON responses
  • Custom-Tools — Define and expose your own MATLAB functions as AI-callable tools

Understanding the System

  • Architecture — System design: engine pool, job executor, session manager, security, output formatting
  • Async-Jobs — Long-running job lifecycle, progress reporting, cancellation
  • Security — Function blocklists, workspace isolation, upload protection, proxy auth patterns

Integration & Troubleshooting

  • Agent-Onboarding — Connection examples for Claude Code, Codex CLI, and Cursor
  • Examples — Ready-to-run MATLAB code: basic ops, plotting, signal processing, async simulations
  • Troubleshooting — Common issues: MATLAB startup, SSE/HTTP connection, blocked functions, performance
  • FAQ — Frequently asked questions

Quick Facts

Item Value
Languages Python 3.10+, MATLAB R2022b+, Objective-C (via MATLAB Engine API)
Package matlab-mcp-python on PyPI
Entry Point matlab-mcp CLI command
Config Format YAML with environment variable overrides
Transport Modes stdio (local), SSE (remote, deprecated), streamable HTTP (remote, recommended)
Auth Bearer token via MATLAB_MCP_AUTH_TOKEN env var; no OAuth complexity
Built-in Tools 20 tools across code execution, discovery, jobs, files, monitoring
Testing 840+ tests, pytest with asyncio, full CI/CD coverage
Codebase 6,259 lines of core Python; layered architecture with isolated concerns
Docker Official image at ghcr.io/hansur94/matlab-mcp-server-python

Common Use Cases

Single Developer (Local MATLAB)

Use stdio transport with your local MATLAB installation:

matlab-mcp --transport stdio

Configure Claude Desktop or Cursor to connect via stdio.

Shared Team Server

Use streamable HTTP with bearer token auth and session isolation:

export MATLAB_MCP_AUTH_TOKEN=$(python -c "import secrets; print(secrets.token_hex(32))")
matlab-mcp --transport streamablehttp --host 127.0.0.1 --port 8765

Multiple agents connect with the same auth token; each gets its own session/workspace.

Academic Cluster / HPC

Use stateless HTTP mode for horizontal scaling without sticky sessions:

server:
  transport: streamablehttp
  stateless_http: true

Deploy behind a load balancer; no session affinity required.

Custom MATLAB Libraries

Expose proprietary functions as first-class tools:

custom_tools:
  config_file: ./my_tools.yaml

Agents call your functions like built-in tools with type validation and help text.

Enterprise Deployment

Combine HITL approval gates, IP-based access control, and function scoping:

hitl:
  enabled: true
  protected_functions: ["delete", "rmdir"]
  all_execute: false

Sensitive operations pause for human approval before execution.

Getting Help

Last updated: April 2026 | Version: v2.0 | Status: Production

Clone this wiki locally