Execute and Manage MATLAB Code

MATLAB MCP Tool

A Model Context Protocol (MCP) server that provides tools for developing and running MATLAB files. Integrates with Claude Code, Cursor, and other MCP-compatible clients.

Prerequisites

• Python 3.10+
• MATLAB with Python Engine installed
• uv package manager (required)

Features

1. Script Execution - Run complete scripts, individual sections (by index, title, or line range), maintain workspace context between executions, capture plots
2. Workspace Management - Get full workspace, retrieve specific variables with field/depth/size control, inspect struct metadata, list and filter variables by name pattern or type
3. Figure Analysis - Extract figure metadata (axes, labels, legends), get raw plot data, prepare figures for LLM-based analysis with custom prompts
4. Code Quality - Lint MATLAB code via checkcode with severity filtering, supports inline code and file paths
5. Script Management - Create scripts, list sections with previews, read script content via MCP resource

Installation

Quick Start (Recommended)

One-command installation with auto-detection:

./install-matlab-mcp.sh

That's it! The installer will:

• ✅ Auto-detect MATLAB installations (including external volumes like /Volumes/S1/)
• ✅ Auto-install UV package manager if needed
• ✅ Create optimized virtual environment with MATLAB-compatible Python version
• ✅ Install all dependencies including MATLAB Python engine
• ✅ Generate MCP configuration ready for Cursor/Claude Code
• ✅ Verify installation works correctly
• ✅ Optionally configure Cursor automatically

Reduces installation time from 15+ minutes to ~2 minutes!

Advanced Installation

If you need custom configuration:

1. Clone this repository:

git clone [repository-url]
cd matlab-mcp-tools

2. Set custom MATLAB path (optional - installer auto-detects):

# Only needed if MATLAB is in unusual location
export MATLAB_PATH=/path/to/your/matlab/installation

3. Run installer:

./install-matlab-mcp.sh

Legacy Installation (Manual)

# Install uv using Homebrew
brew install uv
# OR install using pip
pip install uv

# For macOS (auto-detection searches common locations)
export MATLAB_PATH=/Applications/MATLAB_R2024b.app

# For Windows (use Git Bash terminal)
export MATLAB_PATH="C:/Program Files/MATLAB/R2024b"

./scripts/setup-matlab-mcp.sh

cp mcp-pip.json ~/.cursor/mcp.json

Testing Installation

Test your installation:

./scripts/test-matlab-mcp.sh

Installation complete! The MATLAB MCP server is now ready to use with Cursor/Claude Code.

Usage

1. Start the MCP server:

matlab-mcp-server

This is equivalent to running:

python -m matlab_mcp.server

You should see a startup message confirming the server is running with 15 tools available.

2. Configure your MCP client. For Claude Code, add to .mcp.json:

{
  "mcpServers": {
    "matlab": {
      "command": "/path/to/matlab-mcp-tools/.venv/bin/matlab-mcp-server",
      "env": {
        "MATLAB_PATH": "/Applications/MATLAB_R2024b.app"
      }
    }
  }
}

For Cursor, use the auto-generated mcp-pip.json or add to ~/.cursor/mcp.json.

Hint: Find the MATLAB engine path with python -c "import matlab; print(matlab.__file__)".

3. Available Tools (15):

Resource: matlab://scripts/{script_name} - Read script content

Examples

1. Simple Script Execution with Plot

This example demonstrates running a complete MATLAB script that generates a plot:

% test_plot.m
x = linspace(0, 2*pi, 100);
y = sin(x);

% Create a figure with some styling
figure;
plot(x, y, 'LineWidth', 2);
title('Sine Wave');
xlabel('x');
ylabel('sin(x)');
grid on;

% Add some annotations
text(pi, 0, '\leftarrow \pi', 'FontSize', 12);

To execute this script using the execute_script tool:

{
    "script": "test_plot.m",
    "is_file": true
}

The tool will execute the script and capture the generated plot, saving it to the output directory.

2. Section-Based Execution

This example shows how to execute specific sections of a MATLAB script:

%% Section 1: Data Generation
% Generate sample data
x = linspace(0, 10, 100);
y = sin(x);

fprintf('Generated %d data points\n', length(x));

%% Section 2: Basic Statistics
% Calculate basic statistics
mean_y = mean(y);
std_y = std(y);
max_y = max(y);
min_y = min(y);

fprintf('Statistics:\n');
fprintf('Mean: %.4f\n', mean_y);
fprintf('Std Dev: %.4f\n', std_y);
fprintf('Max: %.4f\n', max_y);
fprintf('Min: %.4f\n', min_y);

%% Section 3: Plotting
% Create visualization
figure('Position', [100, 100, 800, 400]);

subplot(1, 2, 1);
plot(x, y, 'b-', 'LineWidth', 2);
title('Signal');
xlabel('x');
ylabel('y');
grid on;

subplot(1, 2, 2);
histogram(y, 20);
title('Distribution');
xlabel('Value');
ylabel('Count');
grid on;

sgtitle('Signal Analysis');

To execute specific sections using execute_section_by_index:

{
    "file_path": "section_test.m",
    "section_index": 0
}

Or by title using execute_section_by_title:

{
    "file_path": "section_test.m",
    "section_title": "Data Generation"
}

The output will include:

Generated 100 data points
Statistics:
Mean: 0.0000
Std Dev: 0.7071
Max: 1.0000
Min: -1.0000

Output Directory

The tool creates matlab_output and test_output directories to store:

• Plot images generated during script execution
• Other temporary files

Error Handling

• Script execution errors are captured and returned with detailed error messages
• Workspace state is preserved even after errors

Installation Troubleshooting

The new install-matlab-mcp.sh installer handles most common issues automatically. If you encounter problems:

Common Issues and Solutions

1. MATLAB not found:

• The installer auto-detects MATLAB in common locations
• If you have MATLAB in unusual location: export MATLAB_PATH=/your/matlab/path
• Supported locations include external volumes (e.g., /Volumes/S1/Applications/)

2. UV package manager issues:

• The installer automatically installs UV if needed
• For manual installation: curl -LsSf https://astral.sh/uv/install.sh | sh

3. Python version compatibility:

• Installer automatically selects MATLAB-compatible Python version
• MATLAB R2024b: Python 3.11, R2024a: Python 3.10, R2023x: Python 3.9

4. Permission errors:

• Run installer with appropriate permissions
• On Windows: use Git Bash with Admin privileges

5. Configuration issues:

• Use the auto-generated mcp-pip.json configuration
• Installer offers automatic Cursor configuration

Legacy Issues (if using manual installation)

{
    "command": "bash",
    "args": ["-c", "source ~/.zshrc && /path/to/matlab-mcp-install/.venv/bin/matlab-mcp-server"]
}

Still Having Issues?

1. Check installer output for specific error messages
2. Verify MATLAB license is valid and active
3. Test manually: .venv/bin/matlab-mcp-server --help
4. Open an issue with installer output if problem persists