MATLAB MCP Bridge

A lightweight, zero-dependency MCP server that bridges Claude Code (and other MCP clients) to MATLAB via subprocess calls. Each invocation starts matlab -batch, making it simple, reliable, and compatible with any Python version.

Claude Code ──MCP(stdin/stdout)──> Python Server ──subprocess──> matlab -batch
                                   + helpers/*.m (MATLAB helper functions)

Why This Exists

MATLAB's official Engine API for Python only supports Python 3.9–3.12. If you're on Python 3.13+ (as many are in 2026), the Engine API won't work. This bridge uses subprocess mode — launching matlab -batch for each call — which works with any Python version and requires zero MATLAB configuration.

Trade-off: Each call takes ~10–20 seconds (MATLAB cold start). Workspace variables are persisted across calls via .mat files.

Features

5 MCP Tools: matlab_run · matlab_eval · matlab_workspace · matlab_lint · matlab_figure
Smart Workspace: Variables listed with type, size, and memory footprint (whos-based)
Tiered Variable Retrieval: Small arrays → full data; Medium → stats + sample; Large → metadata only
Code Linting: MATLAB's checkcode / mlint with line numbers, severity, and message IDs
Figure Analysis: Extract axis labels, line colors/styles, legend entries, and data dimensions
Workspace Persistence: Variables carry over between calls via matlab_workspace.mat
Modular Helpers: MATLAB helper functions in helpers/ — easy to extend

Quick Start

Prerequisites

Python 3.9+
MATLAB R2020b or later
Claude Code (or any MCP-compatible client)

1. Configure MATLAB Path

Edit matlab_subprocess_server.py line 29:

MATLAB_EXE = r"D:\Program Files\MATLAB\R2024b\bin\matlab.exe"

Or set the MATLAB_EXE environment variable.

2. Add to Claude Code

In your project's .mcp.json:

{
  "mcpServers": {
    "matlab-bridge": {
      "command": "python",
      "args": ["matlab_subprocess_server.py"],
      "cwd": ".",
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Or in claude_desktop_config.json:

{
  "mcpServers": {
    "matlab-bridge": {
      "command": "python",
      "args": ["D:/matlab-mcp-bridge/matlab_subprocess_server.py"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

3. Restart Claude Code

Run /mcp to verify matlab-bridge is online with 5 tools.

Tools Reference

`matlab_run`

Execute MATLAB code with full workspace persistence.

x = 1:10; y = sin(x); plot(x, y, 'LineWidth', 2);

`matlab_eval`

Evaluate an expression with smart result sizing.

| Expression | Result | |------------|--------| | mean(1:100) | 50.5 | | rand(5) | Full 5x5 matrix | | rand(1000,1) | Stats: min/max/mean/std + 3-element sample |

`matlab_workspace`

Manage workspace: list variables, get values, or clear.

Workspace: 3 variable(s), 0.002 MB total

Name                 Class        Size             MB
------------------------------------------------------------
A                    double       3x3              0.000069
x                    double       1x100            0.000763
y                    double       1x100            0.000763

`matlab_lint`

Check MATLAB code for issues using checkcode (mlint).

MATLAB Code Analyzer: 2 issues found

  L3:12 [WARNING] [NASGU] Value assigned to 'x' might be unused.
  L5:1  [INFO]    Terminate statement with semicolon to suppress output.

`matlab_figure`

Extract metadata from figures: axes, labels, line colors/styles, legend.

Figure 1 "Trig Functions": 1 axes

  Axes 1:
    Title:  Trigonometric Functions
    X:      Angle (rad) [linear, 0.0, 7.0]
    Y:      Value [linear, -1.0, 1.0]
    Lines:  2
      • - none [1.0, 0.0, 0.0] "sin"  (X: [1, 100], Y: [1, 100])
      • -- none [0.0, 0.0, 1.0] "cos"  (X: [1, 100], Y: [1, 100])
  Legend: ['sin', 'cos']

Architecture

matlab-mcp-bridge/
├── matlab_subprocess_server.py   # Python MCP server (stdio transport)
├── helpers/
│   ├── mcp_whos.m                # Workspace enumeration
│   ├── mcp_getvar.m              # Smart variable retrieval (3 tiers)
│   ├── mcp_lint.m                # Code quality checker
│   └── mcp_figure_info.m         # Figure metadata extraction
├── plots/                        # Generated plots (auto-created)
├── matlab_workspace.mat          # Workspace persistence (auto-created)
├── .gitignore
├── LICENSE
└── README.md

Data Flow

MCP client sends JSON-RPC request via stdin
Python server parses the tool call
Constructs a matlab -batch command string (single-quoted, no newlines)
Injects addpath('helpers/') so MATLAB helper functions are available
Optionally loads matlab_workspace.mat before execution
MATLAB executes the code
Result is captured via JSON markers (__WSJSON__, __GETVARJSON__, etc.)
Optionally saves workspace back to matlab_workspace.mat
Python parses the marker and returns structured result via stdout

Variable Retrieval Tiers

| Array Size | Mode | Returned Content | |------------|------|------------------| | ≤ 100 elements | full | Complete data | | 100 – 10,000 | summary | 3-element sample + min/max/mean/std | | > 10,000 | metadata | Size, type, statistics only |

Important Constraints

MATLAB strings MUST use single quotes '...' — Windows -batch strips double quotes
Figures are not persisted across calls (fresh MATLAB instance each time)
Each call takes ~10–20 seconds due to MATLAB cold start
Chinese paths are supported (tested on Chinese Windows)

Design Credits

This project draws inspiration from:

matlab-mcp-tools — three-tier workspace classification, field retrieval, figure analysis
subspace-lab/matlab-mcp-server — consolidated multi-operation tools, mode architecture
MATLAB MCP Core Server (MathWorks) — checkcode integration, subprocess architecture

Troubleshooting

| Problem | Solution | |---------|----------| | MATLAB not found | Update MATLAB_EXE path in the server file | | "text string invalid" error | Use single quotes '...' not double quotes "..." in MATLAB code | | Helpers not found | Ensure helpers/ directory exists with all 4 .m files | | Timeout | Increase BATCH_TIMEOUT (default 120s) | | Encoding issues | The server uses native2unicode/unicode2native for UTF-8 |

License

MIT — see LICENSE for details.

MCP Servers