MATLAB MCP Tool

A Model Context Protocol (MCP) server that provides tools for developing and running MATLAB files. This tool integrates with Cline and other MCP-compatible clients to provide interactive MATLAB development capabilities.

Prerequisites

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

Features

1. Execute MATLAB Scripts

   • Run complete MATLAB scripts
   • Execute individual script sections
   • Maintain workspace context between executions
   • Capture and display plots

2. Section-based Execution

   • Execute specific sections of MATLAB files
   • Support for cell mode (%% delimited sections)
   • Maintain workspace context between sections

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)

Click to expand legacy manual installation steps

1. Install uv package manager:

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

2. Set MATLAB path environment variable:

# 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"

3. Run legacy setup script:

./scripts/setup-matlab-mcp.sh

4. Configure Cursor manually:

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 listing the available tools and confirming the server is running:

MATLAB MCP Server is running...
Available tools:
  - execute_script: Execute MATLAB code or script file
  - execute_script_section: Execute specific sections of a MATLAB script
  - get_script_sections: Get information about script sections
  - create_matlab_script: Create a new MATLAB script
  - get_workspace: Get current MATLAB workspace variables

Use the tools with Cline or other MCP-compatible clients.

2. Use the provided MCP configuration (see Installation) file to configure Cline/Cursor:

{
  "mcpServers": {
    "matlab": {
      "command": "matlab-mcp-server",
      "args": [],
      "env": {
        "MATLAB_PATH": "${MATLAB_PATH}",
        "PATH": "${MATLAB_PATH}/bin:${PATH}"
      },
      "disabled": false,
      "autoApprove": [
        "list_tools",
        "get_script_sections"
      ]
    }
  }
}

Hint: You can find the MATLAB engine installation path by running python -c "import matlab; print(matlab.__file__)".

3. Available Tools:

• execute_matlab_script

  {
    "script": "x = 1:10;\nplot(x, x.^2);",
    "isFile": false
  }

• execute_matlab_section

  {
    "filePath": "analysis.m",
    "sectionStart": 1,
    "sectionEnd": 10
  }

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 MCP tool:

{
    "script": "test_plot.m",
    "isFile": 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:

{
    "filePath": "section_test.m",
    "sectionStart": 1,
    "sectionEnd": 2
}

This will run sections 1 and 2, generating the data and calculating statistics. 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)

Click for legacy troubleshooting

1. Make sure uv is installed before running legacy scripts
2. For ENONET errors, ensure Python executable consistency:

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

3. MATLAB Python Engine compatibility: See MATLAB Engine docs

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

Contributing

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

License

This project is licensed under the BSD-3-Clause License. See the LICENSE file for details.