How to Configure MatlabMCP in Claude Desktop with Absolute Paths and uv

To configure MatlabMCP in Claude Desktop, add an absolute path to the uv executable and the repository directory in claude_desktop_config.json, then restart Claude Desktop to enable MATLAB code execution through the Model Context Protocol.

MatlabMCP is a lightweight Python server that bridges Claude Desktop with the MATLAB Engine API, allowing LLM agents to execute MATLAB code and query workspace variables directly. Because Claude Desktop spawns MCP servers in a sandboxed environment, you must use absolute paths and the uv package manager to ensure the server launches correctly regardless of the working directory.

Prerequisites for MatlabMCP Configuration

Before editing Claude Desktop's configuration, ensure you have installed the required dependencies and cloned the repository to a permanent location.

Installing uv and MATLAB Engine

You need uv (the fast Python package manager) and the MATLAB Engine API for Python installed on your system.

1. Install uv by following the official instructions for your platform.
2. Clone the jigarbhoye04/matlabmcp repository to a fixed path (e.g., C:\Tools\MatlabMCP on Windows or /opt/matlabmcp on Linux/macOS).
3. Inside the repository directory, create a virtual environment and install dependencies:

uv venv
uv pip sync

This reads pyproject.toml and uv.lock to install matlabengine, fastapi, and other required packages.

Understanding the Claude Desktop Configuration File

Claude Desktop stores MCP server definitions in a JSON configuration file located at:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

When Claude Desktop starts, it reads the mcpServers object and spawns a subprocess for each entry, capturing stdout/stderr and exchanging JSON-RPC messages over stdio.

Step-by-Step Configuration with Absolute Paths

To avoid "working directory not found" errors, you must specify absolute paths for both the uv executable and the --directory argument pointing to the MatlabMCP repository.

Locating the uv Executable

Find the absolute path to your uv binary:

• Windows: Typically C:\Users\<Username>\.local\bin\uv.exe or wherever you installed it.
• macOS/Linux: Typically ~/.local/bin/uv or /usr/local/bin/uv.

Use the full path rather than relying on the system PATH environment variable, as Claude Desktop's sandbox may not inherit your shell's environment.

Configuring the Server Entry in claude_desktop_config.json

Open claude_desktop_config.json in a text editor and add the following entry under mcpServers, replacing the placeholder paths with your actual absolute paths:

{
  "mcpServers": {
    "MatlabMCP": {
      "command": "C:\\Users\\YourName\\.local\\bin\\uv.exe",
      "args": [
        "--directory",
        "C:\\Users\\YourName\\Desktop\\MatlabMCP\\",
        "run",
        "main.py"
      ]
    }
  }
}

Critical details:

• The command field must contain the absolute path to the uv executable.
• The --directory argument must contain the absolute path to the folder containing main.py.
• The run main.py arguments tell uv to execute the FastAPI-based MCP server defined in main.py, which wraps MATLAB Engine calls in asyncio.to_thread to keep the event loop responsive.

Starting the Shared MATLAB Engine

Before Claude Desktop can execute MATLAB code, you must start a shared MATLAB Engine session from the MATLAB client. In the MATLAB command window, run:

matlab.engine.shareEngine

This command makes the MATLAB session discoverable by matlab.engine.connect_matlab() in main.py. The MatlabMCP server attaches to this existing session rather than spawning a new MATLAB process, allowing Claude to access your workspace variables and execute commands in your current MATLAB environment.

Verifying the Integration

After saving claude_desktop_config.json and starting the shared MATLAB engine:

1. Restart Claude Desktop completely to reload the MCP configuration.
2. Look for the MatlabMCP server in Claude's settings under "Developer" → "MCP Servers". A green status indicator confirms the server spawned successfully.
3. Test the connection by asking Claude to execute a simple MATLAB command (e.g., x = 5+5). Claude will invoke the runMatlabCode tool defined in main.py.
4. Check the MCP logs for debugging:
   • macOS: ~/Library/Logs/Claude/mcp-server-MatlabMCP.log
   • Windows: %APPDATA%\Claude\Logs\mcp-server-MatlabMCP.log

Troubleshooting Common Path Issues

If Claude Desktop fails to start the MatlabMCP server, the error usually relates to path resolution in the sandboxed environment.

Working Directory Errors

Symptom: "No such file or directory" or "working directory not found" in Claude logs.

Solution: Ensure the --directory argument in claude_desktop_config.json uses an absolute path (e.g., C:\Users\Name\MatlabMCP rather than .\MatlabMCP or ~/MatlabMCP). Claude Desktop's working directory when spawning processes is not guaranteed to be your home folder or the repository location.

uv Executable Not Found

Symptom: "command not found" or "uv is not recognized as an internal or external command."

Solution: Use the absolute path to the uv binary in the command field. On Windows, verify the path ends with uv.exe. If you installed uv via cargo or a package manager, locate the binary with where uv (Windows) or which uv (macOS/Linux) and paste the full output into the configuration.

Summary

Configuring MatlabMCP in Claude Desktop requires precise absolute path configuration to bridge the sandboxed Claude environment with the MATLAB Engine API:

• Use absolute paths for both the uv executable and the --directory argument in claude_desktop_config.json to avoid working directory errors.
• Start a shared MATLAB engine with matlab.engine.shareEngine before launching Claude Desktop so main.py can attach via matlab.engine.connect_matlab().
• Restart Claude Desktop after editing the configuration to reload the MCP server definitions and verify the connection via the runMatlabCode and getVariable tools.

Frequently Asked Questions

What is MatlabMCP and how does it work with Claude Desktop?

MatlabMCP is a Model Context Protocol (MCP) server that exposes MATLAB functionality to Claude Desktop through a FastAPI-based Python application. It runs as a separate process that Claude spawns and communicates with via JSON-RPC over stdio. The server in main.py wraps MATLAB Engine API calls in asyncio.to_thread to prevent blocking, allowing Claude to execute MATLAB code and retrieve workspace variables without freezing the interface.

Why must I use absolute paths instead of relative paths in the configuration?

Claude Desktop spawns MCP servers in a sandboxed environment where the working directory is not guaranteed to be the repository location or your home folder. Relative paths like ./MatlabMCP or ~/matlabmcp resolve incorrectly or fail entirely within this context. Absolute paths (e.g., C:\Users\Name\MatlabMCP or /home/user/matlabmcp) ensure the uv executable and the --directory argument point to the correct locations regardless of where Claude Desktop launches the process.

How do I find the absolute path to the uv executable on my system?

Locate the uv binary using your terminal. On Windows, run where uv to display the full path (typically C:\Users\<Username>\.local\bin\uv.exe). On macOS or Linux, run which uv to find the location (commonly ~/.local/bin/uv or /usr/local/bin/uv). Copy the complete output including the filename and paste it into the command field of claude_desktop_config.json without relying on environment variables or shorthand commands.

Can I use a global Python installation instead of uv to run MatlabMCP?

While technically possible by changing the command field to point to python or python.exe and adjusting the args to run main.py directly, this approach is not recommended. The uv method ensures a reproducible virtual environment with locked dependencies from uv.lock, preventing version conflicts with the MATLAB Engine API or FastAPI. If you must use a global Python installation, ensure the matlabengine package is installed in that environment and use absolute paths to the Python executable, though you lose the isolation and reproducibility benefits that uv provides.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}