Metadata-Version: 2.4
Name: matlab-simulink-mcp
Version: 0.1.6
Summary: An MCP server for allowing LLMs to interact with MATLAB and Simulink
Author: Rohail
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.12.2
Requires-Dist: platformdirs>=4.4.0
Requires-Dist: setuptools>=80.9.0
Dynamic: license-file

# MATLAB Simulink MCP Server

This **Model Context Protocol (MCP)** server lets MCP clients (such as Claude Desktop or other LLM-based agents) to interact with **MATLAB** and **Simulink** in real time. It runs locally, is built on [FastMCP 2.0](https://gofastmcp.com/getting-started/welcome), and communicates with MATLAB and Simulink via the MATLAB Engine for Python API.

## Features

- **Allows an LLM client to**
  - Read, write, and execute MATLAB code and scripts
  - Parse and interact with Simulink models
  - Access workspace and results (inculding visualizations)

- **Execution Safety**
  - Basic safeguards against unsafe commands
  - Restricted to current working directory (only manually changeable)

- **Robust Runtime**
  - Non-blocking execution (asyncronous MATLAB engine calls)
  - Automatic installation of MATLAB Engine library if unavailable

## Requirements

- **MATLAB** R2022b or later  
- **Python** 3.10–3.12 (check [which version](https://www.mathworks.com/support/requirements/python-compatibility.html) is supported by your MATLAB installation)

## Installation

1. Create and activate a Python virtual environment ([uv](https://pypi.org/project/uv/0.1.32/) is recommended, automatically installs Python version if missing):

    ```bash
    uv venv --python 3.12           # match Python to your MATLAB-supported version
    source .venv/Scripts/activate   # on macOS/Linux: source .venv/bin/activate
    ```

    Without uv, you will first need to download and install the required Python version manually:

    ```bash
    python3.12 -m venv .venv        # match Python to your MATLAB-supported version
    source .venv/Scripts/activate   # on macOS/Linux: source .venv/bin/activate
    ```

2. Install:

    ```bash
    uv pip install matlab-simulink-mcp
    # or without uv
    pip install matlab-simulink-mcp
    ```

3. On the first run, if MATLAB Engine is not found, the server will open a console window and guide you through installation.

    - This requires admin permission and the application will request for it.
    - If you prefer to install manually, install a [matching PyPI version](https://pypi.org/project/matlabengine/#history) or from your [MATLAB installation](https://www.mathworks.com/help/matlab/matlab_external/install-the-matlab-engine-for-python.html).

## Configuration

### Claude Desktop

1. Open [Claude Desktop](https://claude.ai/download) Settings → Developer → Edit Config.

2. In the `claude_desktop_config.json`, add or update:

    ```json
    {
    "mcpServers": {
        "MATLAB_Simulink_MCP": {
            "command": "<absolute-path-to>/.venv/Scripts/python.exe", // absolute path to your Python environment executable
            "args": [
                "-m", 
                "matlab_simulink_mcp"
                ],
            "env": {
                "LOG_DIR": "<absolute-path-to>/logs" // Optional: absolute path to a folder for logs
                }
            }
        }
    }
    ```

3. Save and restart Claude Desktop. (Ensure it is fully closed in Task Manager/Activity Monitor.)

4. Server's status can be checked from Settings → Developer, or the equalizer button in Claude's chat box.

### Claude Code / Codex CLI

1. Run the following command in terminal:

    ```bash
    claude mcp add MATLAB_Simulink_MCP --env LOG_DIR="<absolute-path-to>/logs" -- "<absolute-path-to>/.venv/bin/python" -m matlab_simulink_mcp
    ```

    For Codex CLI, use ```codex``` instead of ```claude```.

2. Restart by opening a new terminal.

3. To check server status, run ```claude mcp list``` or ```codex mcp list```.

For more information, see documentation for [Claude Code](https://code.claude.com/docs/en/mcp#option-3%3A-add-a-local-stdio-server) or [Codex CLI](https://developers.openai.com/codex/mcp).

### Notes

1. On macOS/Linux, use `<absolute-path-to>/.venv/bin/python` instead for the path to Python.

2. Only use `/` or `\\` in the paths, not `\`.

3. On first launch, the server may open multiple consoles to install MATLAB Engine. Interact with one, complete installation, then restart the application if needed.

4. Any client is restricted to the current MATLAB working directory, which can only be changed manually for safety reasons.

5. The server logs outputs and errors its own log file as well. To keep a log file tracking console open, add `"--console"` to config args. The log file is in the folder specified via environment variable `LOG_DIR`, or otherwise in the user log directory.

## Debugging

FastMCP 2.0 includes an [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for manual testing and debugging without an LLM client. It launches a web UI to send dummy requests directly to the server. The inspector finds and runs a server object named `mcp` itself. So you will need to `import matlab_simulink_mcp.server.mcp as mcp` in a script and then run it:

```bash
fastmcp dev script_name.py
```
