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

> Learn to configure MatlabMCP in Claude Desktop using absolute paths and the uv executable. Follow our guide to integrate MATLAB code execution seamlessly and restart Claude Desktop for changes to take effect.

- Repository: [Jigar Bhoye/matlabmcp](https://github.com/jigarbhoye04/matlabmcp)
- Tags: how-to-guide
- Published: 2026-03-04

---

**To configure MatlabMCP in Claude Desktop, add an absolute path to the `uv` executable and the repository directory in [`claude_desktop_config.json`](https://github.com/jigarbhoye04/matlabmcp/blob/main/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:

```bash
uv venv
uv pip sync

```

This reads [`pyproject.toml`](https://github.com/jigarbhoye04/matlabmcp/blob/main/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`](https://github.com/jigarbhoye04/matlabmcp/blob/main/claude_desktop_config.json) in a text editor and add the following entry under `mcpServers`, replacing the placeholder paths with your actual absolute paths:

```json
{
  "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`](https://github.com/jigarbhoye04/matlabmcp/blob/main/main.py).
- The `run main.py` arguments tell `uv` to execute the FastAPI-based MCP server defined in [`main.py`](https://github.com/jigarbhoye04/matlabmcp/blob/main/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
matlab.engine.shareEngine

```

This command makes the MATLAB session discoverable by `matlab.engine.connect_matlab()` in [`main.py`](https://github.com/jigarbhoye04/matlabmcp/blob/main/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`](https://github.com/jigarbhoye04/matlabmcp/blob/main/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`](https://github.com/jigarbhoye04/matlabmcp/blob/main/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`](https://github.com/jigarbhoye04/matlabmcp/blob/main/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`](https://github.com/jigarbhoye04/matlabmcp/blob/main/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`](https://github.com/jigarbhoye04/matlabmcp/blob/main/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`](https://github.com/jigarbhoye04/matlabmcp/blob/main/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`](https://github.com/jigarbhoye04/matlabmcp/blob/main/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`](https://github.com/jigarbhoye04/matlabmcp/blob/main/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.