Matlab-MCP-Tools

What is matlab-mcp-tools?

matlab-mcp-tools is a Model Context Protocol (MCP) server designed to facilitate the development and execution of MATLAB scripts. It integrates with MCP-compatible clients, such as Cline, to offer an interactive environment for MATLAB programming. This tool allows users to run MATLAB scripts, execute specific sections, maintain workspace context, and visualize plots directly within their development workflow.

How to use matlab-mcp-tools?

To use matlab-mcp-tools, you first need to install it. The recommended method involves using uv and pip.

Clone the repository and navigate into its directory.
Install uv (if not already installed).
Set the MATLAB path environment variable if your MATLAB installation is not in the default location.
Run the setup script (./setup-matlab-mcp.sh) which will create a virtual environment, install necessary packages (including the MATLAB Engine Python package), and generate an MCP configuration file.
Configure your MCP-compatible client (e.g., Cline/Cursor) by copying the generated mcp-config.json file to the appropriate directory.
Start the MCP server by running matlab-mcp-server.

Once the server is running, you can interact with it through your client to execute MATLAB scripts or sections using the provided tools like execute_matlab_script and execute_matlab_section.

Key Features of matlab-mcp-tools

Execute MATLAB Scripts: Run entire MATLAB scripts or individual sections.
Workspace Context Maintenance: Preserve the MATLAB workspace context between executions, allowing for continuous development.
Plot Visualization: Capture and display plots generated by MATLAB scripts.
Section-based Execution: Execute specific sections of MATLAB files, supporting cell mode (%% delimited sections).
Tool Availability: Provides tools such as execute_script, execute_script_section, get_script_sections, create_matlab_script, and get_workspace.
Error Handling: Captures and returns detailed error messages from script execution while preserving workspace state.
Output Management: Creates matlab_output and test_output directories for storing plot images and temporary files.

Use Cases of matlab-mcp-tools

Interactive MATLAB Development: Seamlessly integrate MATLAB script execution and debugging within an MCP-compatible IDE.
Automated Script Testing: Run specific sections of MATLAB code for testing and validation.
Data Analysis and Visualization: Execute MATLAB scripts for data processing and visualize the results directly.
Educational Purposes: Provide an interactive environment for learning and experimenting with MATLAB.

FAQ from matlab-mcp-tools

Q: What are the prerequisites for using matlab-mcp-tools? A: You need Python 3.10+, MATLAB with the Python Engine installed, and the uv package manager.

Q: How do I troubleshoot installation issues? A: Ensure uv is installed, run the setup script from the repository root, verify the Python executable used by your client matches the installation, and confirm MATLAB Python Engine compatibility and license.

Q: Can I run specific sections of a MATLAB script? A: Yes, the tool supports section-based execution, allowing you to run specific cell-delimited sections of your MATLAB files.

Q: Does the tool maintain the MATLAB workspace? A: Yes, it maintains the workspace context between executions, which is crucial for iterative development.

Q: Where are the generated plots and temporary files stored? A: The tool creates matlab_output and test_output directories to store plot images and other temporary files.

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

Execute MATLAB Scripts
- Run complete MATLAB scripts
- Execute individual script sections
- Maintain workspace context between executions
- Capture and display plots
Section-based Execution
- Execute specific sections of MATLAB files
- Support for cell mode (%% delimited sections)
- Maintain workspace context between sections

Installation

Using uv and pip (Recommended)

Clone this repository:

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

Install uv if you don't have it yet:

# Install uv using Homebrew
brew install uv

# Install uv using pip
pip install uv

Alternatively, you can install uv by installing this repository as a development dependency:

pip install -e ".[dev]"

Set the MATLAB path environment variable if your MATLAB is not in the default location:

# For macOS (default is /Applications/MATLAB_R2024b.app)
export MATLAB_PATH=/path/to/your/matlab/installation

# For Windows use Git Bash terminal (default might be C:\Program Files\MATLAB\R2024b)
# Also use forward slashes and double quotes for paths with spaces
# export MATLAB_PATH="C:/path/to/your/matlab/installation"

Run the setup script to create a virtual environment and install the package:

./setup-matlab-mcp.sh

The setup script will:

Check if uv is installed
Create a virtual environment in .venv directory
Install the MATLAB Engine Python package
Install the matlab-mcp-server package in development mode
Generate an MCP configuration file

Configure Cline/Cursor by copying the provided MCP configuration:

# For macOS/Linux
cp mcp-config.json ~/.cursor/mcp.json

# For Windows
# copy mcp-config.json %USERPROFILE%\.cursor\mcp.json

Test the installation:

./test-matlab-mcp.sh

After setup, you can run the MATLAB MCP server using:

matlab-mcp-server

If the server is not found, check whether the server is installed in the virtual environment:

./.venv/bin/matlab-mcp-server

Troubleshooting: See Installation Troubleshooting for common issues and solutions. Don't hesitate to open an issue on the repository if you encounter an issue that is not listed, and a PR if you have a solution.

Usage

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.

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__)".

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

Note that the setup-matlab-mcp.sh script is designed to be run from the root of the repository.
The script is dependent on uv being installed. So make sure you have it installed (pip install uv).
If the scripts run, but you get an ENONET error, make sure that the Python executable used to run the install script is the same Python executable that Cline/Cursor is using. Otherwise, you can specify the Python executable in the MCP configuration file within the command and args keys. For example:

{
      "command": "bash",
      "args": ["-c", "source $(conda info --base)/etc/profile.d/conda.sh && conda activate target_environment && /path/to/your/matlab-mcp-tools/.venv/bin/matlab-mcp-server"],
}

In this case, if you're using Conda, replace target_environment with the name of your Conda environment.

Running the setup-matlab-mcp.sh in Windows requires using Git Bash terminal with ADMIN privileges. This is because the script needs to install the matlab-mcp-tools package and this may require admin privileges.
Matlab Python Engine requires specific versions of Python and MATLAB. See the Matlab Python Engine and the Python Versions Compatibility documentations for more information.
Matlab requires a license to be running to use the Python Engine.

Contributing

Fork the repository
Create a feature branch
Submit a pull request

License

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

Matlab-MCP-Tools Overview