MATLAB MCP Server: Execute, Analyze, Visualize Code

Overview

The MATLAB MCP Server is a small HTTP/JSON service that exposes a persistent MATLAB runtime over the Model Context Protocol (MCP). It lets clients execute MATLAB code remotely while keeping a live workspace, capture generated figures, and interactively inspect variables and specific script sections. The server is intended for developers who want to integrate MATLAB execution into tools, notebooks, or multi-step workflows without launching a fresh MATLAB process for every call.

By preserving the MATLAB workspace across requests, the server supports iterative data exploration and long-running analysis pipelines. It also provides endpoints to serialize variable values, list and download figures, run sections of live scripts, and reset or snapshot the workspace. This approach reduces overhead (no repeated engine startup), simplifies stateful debugging, and makes combining MATLAB computations with web-based UIs or language-model agents straightforward.

Features

• Execute arbitrary MATLAB statements and return stdout, stderr, and return values
• Persistent MATLAB workspace across requests (variables remain available)
• Run only selected sections of a live script (.mlx/.m sections)
• Capture and return figures as PNG/SVG images
• Inspect and serialize variables (JSON-friendly formats, limited-size binaries)
• Workspace snapshot and reset endpoints
• Lightweight HTTP/JSON API suitable for integration with notebooks, CLIs, and agents

Installation / Configuration

Prerequisites

• MATLAB installed on the same host (MATLAB Engine API or ability to call MATLAB)
• Python 3.8+ (if the server is implemented in Python)
• Git

Clone and install

git clone https://github.com/neuromechanist/matlab-mcp-tools.git
cd matlab-mcp-tools
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configure (example config.yaml)

# config.yaml
host: 127.0.0.1
port: 8000
preserve_workspace: true
workspace_dir: ./mcp_workspace
capture_figures: true
figure_format: png
max_variable_serialized_bytes: 1000000

Start the server

# environment variable alternative
export MCP_CONFIG=./config.yaml
python -m matlab_mcp_server.server --config ./config.yaml

Notes

• Ensure the user running the server has permissions to launch MATLAB.
• Configure a dedicated workspace directory to persist scripts, MAT-files, and generated plots.
• Consider running behind a reverse proxy for authentication and TLS in production.

Available Resources

The server exposes a small set of HTTP endpoints (JSON requests/responses). Common endpoints:

• POST /execute

  • Body: { “code”: “”, “timeout”: 60 }
  • Executes code in the persistent workspace. Returns stdout, stderr, and a summary of modified variables.

  • POST /execute_section

    • Body: { “file”: “analysis.m”, “section_id”: 2 }
    • Runs a single section from a script or live script.

  • GET /workspace

    • Returns a compact listing of workspace variables and their types/sizes.

  • POST /variable

    • Body: { “name”: “myVar”, “format”: “json” }
    • Returns serialized variable content (JSON for numeric/scalar/arrays, base64 for blobs if needed).

  • GET /figures

    • Lists available figure IDs and metadata.

  • GET /figure/

    • Returns a PNG/SVG image for a given figure.

  • POST /reset

    • Resets the MATLAB workspace (clears variables, closes figures).

  Example: execute with curl

  curl -sS -X POST http://localhost:8000/execute \
    -H "Content-Type: application/json" \
    -d '{"code":"x = rand(100); y = mean(x,2); disp(min(y));","timeout":10}'
  

  Example: fetch a figure

  curl http://localhost:8000/figure/1 --output figure1.png
  

  Use Cases

  1. Notebook-backed data exploration

     • Use the server from a Jupyter notebook to run heavy MATLAB computations while preserving intermediate variables. Generate figures remotely and embed returned PNGs directly into the notebook without launching a local MATLAB GUI.

  2. Automated analysis pipelines

     • Orchestrate multi-step MATLAB analyses from a Python or Node.js controller. Each pipeline step runs MATLAB code that reads/writes variables in the persistent workspace, enabling handoffs without file I/O.

  3. Interactive debugging and section testing

     • Run only a specific section of a live script to test changes quickly. Inspect variables before and after section runs to validate fixes or tune parameters without restarting MATLAB.

  4. Integration with language model agents or web UIs

     • Provide an agent or frontend the ability to execute MATLAB snippets, request variable state, and retrieve plots. The MCP server supplies the necessary endpoints and statefulness for conversational debugging workflows.

  Tips and Best Practices

  • Limit variable serialization sizes; retrieve large arrays via MAT-files if needed.
  • Use workspace snapshots (save/load .mat) for reproducible checkpoints.
  • Secure the server in production (authentication, TLS, firewall rules).
  • Prefer section execution for iterative development to reduce side effects across long scripts.

  This server is intended as a developer tool to make MATLAB workflows scriptable and accessible over a simple, stateful HTTP interface. Refer to the repository for implementation details, example clients, and production deployment tips.

  Tags:developer-tools