Skip to content

Commit 617f3e7

Browse files
neuromechanistneuromechanist
committed
Initial implementation: Basic MATLAB script execution and plot handling
- Added MATLAB engine wrapper with script execution support - Implemented plot capture and workspace variable handling - Added basic MCP server with tools for script execution - Created example test script and server test
0 parents  commit 617f3e7

File tree

13 files changed

+1445
-0
lines changed

13 files changed

+1445
-0
lines changed

‎.gitignore

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
*.so
6+
.Python
7+
build/
8+
develop-eggs/
9+
dist/
10+
downloads/
11+
eggs/
12+
.eggs/
13+
lib/
14+
lib64/
15+
parts/
16+
sdist/
17+
var/
18+
wheels/
19+
*.egg-info/
20+
.installed.cfg
21+
*.egg
22+
23+
# Virtual environments
24+
.env
25+
.venv
26+
env/
27+
venv/
28+
ENV/
29+
30+
# IDE
31+
.idea/
32+
.vscode/
33+
*.swp
34+
*.swo
35+
36+
# MATLAB
37+
*.asv
38+
*.m~
39+
*.mex*
40+
slprj/
41+
sccprj/
42+
codegen/
43+
octave-workspace
44+
45+
# Project specific
46+
matlab_output/
47+
test_output/
48+
matlab_scripts/
49+
50+
# Development files
51+
examples/matlab_scripts/section_test.m

‎LICENSE

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
BSD 3-Clause License
2+
3+
Copyright (c) 2025 Seyed Yahya Shirazi
4+
All rights reserved.
5+
6+
Redistribution and use in source and binary forms, with or without
7+
modification, are permitted provided that the following conditions are met:
8+
9+
1. Redistributions of source code must retain the above copyright notice, this
10+
list of conditions and the following disclaimer.
11+
12+
2. Redistributions in binary form must reproduce the above copyright notice,
13+
this list of conditions and the following disclaimer in the documentation
14+
and/or other materials provided with the distribution.
15+
16+
3. Neither the name of the copyright holder nor the names of its
17+
contributors may be used to endorse or promote products derived from
18+
this software without specific prior written permission.
19+
20+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎README.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# MATLAB MCP Tool
2+
3+
A Model Context Protocol (MCP) server that provides tools for developing, running, and debugging MATLAB files. This tool integrates with Cline and other MCP-compatible clients to provide interactive MATLAB development capabilities.
4+
5+
## Prerequisites
6+
7+
- Python 3.8+
8+
- MATLAB with Python Engine installed
9+
- MCP SDK for Python (`pip install modelcontextprotocol`)
10+
- MATLAB Engine for Python (`pip install matlabengine`)
11+
12+
## Features
13+
14+
1. **Execute MATLAB Scripts**
15+
- Run complete MATLAB scripts
16+
- Execute individual script sections
17+
- Maintain workspace context between executions
18+
- Capture and display plots
19+
20+
2. **Interactive Debugging**
21+
- Set breakpoints in MATLAB scripts
22+
- Debug script execution
23+
- Inspect workspace variables
24+
25+
3. **Section-based Execution**
26+
- Execute specific sections of MATLAB files
27+
- Support for cell mode (%% delimited sections)
28+
- Maintain workspace context between sections
29+
30+
## Installation
31+
32+
1. Clone this repository:
33+
```bash
34+
git clone [repository-url]
35+
cd matlab-mcp-tool
36+
```
37+
38+
2. Create and activate a conda environment:
39+
```bash
40+
conda create -n matlab-mcp python=3.8
41+
conda activate matlab-mcp
42+
```
43+
44+
3. Install dependencies:
45+
```bash
46+
pip install modelcontextprotocol matlabengine
47+
```
48+
49+
## Usage
50+
51+
1. Start the MCP server:
52+
```bash
53+
python src/matlab_bridge.py
54+
```
55+
56+
2. Configure Cline to use the MATLAB MCP server by adding to your Cline configuration:
57+
```json
58+
{
59+
"mcpServers": {
60+
"matlab": {
61+
"command": "python",
62+
"args": ["/path/to/matlab-mcp-tool/src/matlab_bridge.py"],
63+
"env": {
64+
"PYTHONPATH": "/path/to/matlab/engine/installation"
65+
}
66+
}
67+
}
68+
}
69+
```
70+
71+
3. Available Tools:
72+
73+
- **execute_matlab_script**
74+
```json
75+
{
76+
"script": "x = 1:10;\nplot(x, x.^2);",
77+
"isFile": false
78+
}
79+
```
80+
81+
- **execute_matlab_section**
82+
```json
83+
{
84+
"filePath": "analysis.m",
85+
"sectionStart": 1,
86+
"sectionEnd": 10
87+
}
88+
```
89+
90+
- **debug_matlab_script**
91+
```json
92+
{
93+
"script": "debug_script.m",
94+
"breakpoints": [5, 10, 15]
95+
}
96+
```
97+
98+
## Output Directory
99+
100+
The tool creates an `output` directory in the current working directory to store:
101+
- Plot images generated during script execution
102+
- Debug output files
103+
- Other temporary files
104+
105+
## Error Handling
106+
107+
- Script execution errors are captured and returned with detailed error messages
108+
- Workspace state is preserved even after errors
109+
- Debug sessions are properly cleaned up
110+
111+
## Contributing
112+
113+
1. Fork the repository
114+
2. Create a feature branch
115+
3. Submit a pull request
116+
117+
## License
118+
119+
BSD-3-Clause

‎examples/test_server.py

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
"""Test script for MATLAB MCP server."""
2+
3+
import asyncio
4+
from pathlib import Path
5+
6+
from matlab_mcp.server import MatlabServer
7+
8+
9+
async def test_basic_execution():
10+
"""Test basic MATLAB script execution."""
11+
print("Testing MATLAB MCP Server...")
12+
13+
server = MatlabServer()
14+
15+
# Test direct command execution
16+
print("\nTesting direct command execution...")
17+
result = await server.engine.execute(
18+
"a = 5; b = 10; c = a + b; fprintf('Sum: %d\\n', c)"
19+
)
20+
print(f"Output: {result.output}")
21+
print(f"Workspace: {result.workspace}")
22+
23+
# Test script file execution
24+
print("\nTesting script file execution...")
25+
script_path = Path("examples/matlab_scripts/test_plot.m")
26+
if not script_path.exists():
27+
print(f"Error: Script not found at {script_path}")
28+
return
29+
30+
result = await server.engine.execute(
31+
str(script_path),
32+
is_file=True
33+
)
34+
print(f"Output: {result.output}")
35+
print(f"Workspace: {result.workspace}")
36+
print(f"Number of figures captured: {len(result.figures)}")
37+
38+
# Save captured figures
39+
output_dir = Path("test_output")
40+
output_dir.mkdir(exist_ok=True)
41+
42+
for i, fig_data in enumerate(result.figures):
43+
output_path = output_dir / f"figure_{i}.png"
44+
output_path.write_bytes(fig_data)
45+
print(f"Saved figure to: {output_path}")
46+
47+
# Clean up
48+
server.engine.cleanup()
49+
print("\nTest completed successfully!")
50+
51+
52+
if __name__ == "__main__":
53+
asyncio.run(test_basic_execution())

0 commit comments

Comments
 (0)