Matlab MCP Tool

What is Matlab MCP Tool about?

Matlab MCP Tool delivers a server that bridges MATLAB with MCP‑compatible editors. It runs MATLAB code, maintains the interactive workspace across calls, and returns results—including generated figures—so that developers can work on MATLAB projects directly from their editor.

How to use Matlab MCP Tool?

1. Install prerequisites – Python 3.10+, MATLAB with the Python Engine, and the uv package manager.
2. Clone the repository and run the provided setup-matlab-mcp.sh script. This creates a virtual environment, installs the MATLAB Engine, and installs the matlab-mcp-server in development mode.
3. Configure your editor by copying mcp-config.json to the appropriate location (e.g., ~/.cursor/mcp.json).
4. Start the server with matlab-mcp-server (or python -m matlab_mcp.server).
5. Invoke tools from the editor or via API calls – e.g., execute_script, execute_script_section, get_workspace.

Key features of Matlab MCP Tool

• Execute whole MATLAB scripts or selected %% sections.
• Preserve workspace variables between executions.
• Capture and return plot images automatically.
• Provide metadata about script sections for editor integration.
• Simple CLI (matlab-mcp-server) and Python module entry point.

Use cases of Matlab MCP Tool

• Interactive development: Write and test MATLAB code inside VS Code, Cursor, or similar editors without leaving the IDE.
• Education and tutorials: Run individual notebook‑style sections to demonstrate concepts step‑by‑step.
• Automated testing: Execute scripts programmatically and verify outputs or generated figures.
• Rapid prototyping: Quickly tweak parameters in a section and see immediate results while keeping the rest of the workspace intact.

FAQ from the Matlab MCP Tool

• Do I need a MATLAB license? Yes, the Python Engine requires a licensed MATLAB installation.
• Which Python versions are supported? Python 3.10 or newer.
• Can I run the server on Windows? Yes, using Git Bash with administrator rights for the setup script.
• What if I get an ENONET error? Ensure the Python interpreter used by the server matches the one used by your editor, or specify the full path in the MCP configuration.
• How are plots returned? Images are saved in a matlab_output folder and their paths are included in the tool response.

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)

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)

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.