# How to Fix the "No shared MATLAB sessions found" Error in matlabmcp: MATLAB‑Side Requirements

> Fix the 'No shared MATLAB sessions found' error by understanding MATLAB side requirements. Ensure the engine sharing script executes and HTTP advertizer runs correctly for seamless integration.

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

---

**The "No shared MATLAB sessions found" error occurs when the MATLAB process has not called `matlab.engine.shareEngine('MATLABMCP')` or the HTTP advertizer is not running on the expected port; resolving it requires launching MATLAB with the correct startup flags and ensuring the engine‑sharing script executes.**

The `matlabmcp` repository ([jigarbhoye04/matlabmcp](https://github.com/jigarbhoye04/matlabmcp)) bridges Python and MATLAB by exposing shared engine sessions over a local HTTP API. When the Python client cannot discover any sessions, the root cause almost always lies on the MATLAB side—specifically, the absence of a properly initialized shared engine. This guide explains the exact MATLAB‑side requirements to eliminate the "No shared MATLAB sessions found" error.

## Understanding the matlabmcp Architecture

`matlabmcp` consists of three cooperating layers:

1. **MATLAB‑side script** – [`start.m`](https://github.com/jigarbhoye04/matlabmcp/blob/main/start.m) runs inside MATLAB. It invokes `matlab.engine.shareEngine('MATLABMCP')` to register the session, then starts a lightweight HTTP server (implemented with MATLAB’s `webserver` or a thin Python bridge) that listens on a configurable port.
2. **Python server wrapper** – [[`main.py`](https://github.com/jigarbhoye04/matlabmcp/blob/main/main.py)](https://github.com/jigarbhoye04/matlabmcp/blob/main/main.py) is executed from the shell. It spawns the MATLAB process with the correct `-r` startup flag, waits for the HTTP endpoint to become ready, and proxies requests between the client and the MATLAB engine.
3. **Python client** – [[`matlabmcp/client.py`](https://github.com/jigarbhoye04/matlabmcp/blob/main/matlabmcp/client.py)](https://github.com/jigarbhoye04/matlabmcp/blob/main/matlabmcp/client.py) queries `http://127.0.0.1:5000/sessions`. If the JSON payload is empty, it raises the `RuntimeError: No shared MATLAB sessions found` that users see.

The error therefore signals that step 1 or step 2 has not completed successfully.

## Prerequisites for Sharing MATLAB Sessions

Before the client can discover anything, the MATLAB environment must satisfy three hard requirements.

### Install the MATLAB Engine for Python

The shared‑session mechanism relies on the official `matlab.engine` package. Build it once per MATLAB installation:

```bash
cd "$MATLABROOT/extern/engines/python"
python -m pip install .

```

Verify the installation by importing the engine inside Python:

```python
import matlab.engine
print(matlab.engine.find_matlab())   # should list shared sessions

```

If `find_matlab()` returns an empty tuple, the engine is not installed correctly.

### Verify MATLAB Version Compatibility

`matlabmcp` uses the Engine API, which is **not** cross‑version compatible. The Python client and the MATLAB process must share the same major release (e.g., both R2023b). Check the version inside MATLAB:

```matlab
disp(version)

```

And on the Python side:

```python
import matlab.engine
eng = matlab.engine.start_matlab()
print(eng.version())

```

Mismatching versions will cause the HTTP advertizer to start, but the client will be unable to attach, yielding the same “No shared sessions” message.

## Launching MATLAB with Session Sharing Enabled

The most common cause of the error is simply forgetting to invoke the sharing script. `matlabmcp` provides a dedicated entry point that must be executed inside the MATLAB process.

### The Correct Startup Command

Open a terminal (Linux/macOS) or Command Prompt (Windows) and run:

```bash
matlab -nosplash -nodesktop -r "matlabmcp.start; pause(inf)"

```

- `-nosplash` – suppresses the MATLAB splash screen (optional but cleaner).
- `-nodesktop` – runs MATLAB without the GUI, which is required for headless servers.
- `-r "matlabmcp.start; pause(inf)"` – executes the `start` function from the `matlabmcp` package and then pauses indefinitely so the process stays alive.

If you prefer to start MATLAB interactively, you can open the MATLAB Command Window and type:

```matlab
matlabmcp.start

```

Either way, the script must complete before the Python client attempts discovery.

### What matlabmcp.start Does (Inside start.m)

The [`start.m`](https://github.com/jigarbhoye04/matlabmcp/blob/main/start.m) script performs three critical operations:

1. **Registers the shared engine** – calls `matlab.engine.shareEngine('MATLABMCP')`, which makes the session visible to `matlab.engine.find_matlab()` and to the HTTP server.
2. **Starts the HTTP advertizer** – launches a lightweight server (implemented with MATLAB’s `webserver` or a thin Python bridge) that listens on `localhost:5000` by default. The server exposes two endpoints:
   - `GET /status` – returns `{"status":"ok"}`.
   - `GET /sessions` – returns a JSON array of shared sessions, e.g., `[{"name":"MATLABMCP","pid":12345}]`.
3. **Keeps the process alive** – enters a `while true` loop with `pause(1)` so MATLAB does not exit and the shared session remains available.

If any step fails (e.g., the port is already in use, or `shareEngine` throws because the Engine for Python is missing), the HTTP server will either crash or start with an empty session list, causing the client to report “No shared MATLAB sessions found”.

## Configuring Network and Port Settings

The HTTP advertizer binds to a TCP port. If the default port is occupied or blocked by a firewall, the client cannot reach the session list.

### Default Port and Firewall Rules

By default, the server listens on **port 5000**. Ensure that:

- No other service (e.g., another MATLAB instance, Jupyter, or Airflow) is bound to `localhost:5000`.
- The local firewall (Windows Defender, iptables, etc.) allows loopback traffic on the chosen port.

If you need to run multiple MATLAB instances or simply avoid port collisions, set the environment variable before launching the server:

```bash
export MATLABMCP_PORT=5001   # Linux/macOS

set MATLABMCP_PORT=5001      # Windows CMD

matlab -nosplash -nodesktop -r "matlabmcp.start; pause(inf)"

```

The `start.m` script reads `getenv('MATLABMCP_PORT')` and falls back to `5000` if undefined.

### Verifying the HTTP Advertizer is Reachable

Before running the Python client, test the endpoint manually:

```bash
curl http://127.0.0.1:5000/sessions

```

You should receive JSON similar to:

```json
{"sessions":[{"name":"MATLABMCP","pid":12345}]}

```

If the command times out or returns `[]`, the MATLAB side has not completed the sharing handshake. Check the MATLAB Command Window (or the terminal where you launched MATLAB) for error messages such as:

- `Undefined function or variable 'matlabmcp'`.  
- `Unable to share engine – Engine for Python not installed`.  
- `Port 5000 already in use`.

## Common Mistakes That Trigger the Error

Even when the installation looks correct, subtle misconfigurations prevent the session from being advertised.

### Using the -nojvm Flag

The MATLAB Engine for Python relies on the Java Virtual Machine (JVM) to marshal data between Python and MATLAB. If you start MATLAB with the `-nojvm` flag, `matlab.engine.shareEngine` will throw an error or silently fail, and the HTTP server will start with an empty session list.

**Fix:** Remove `-nojvm` from the launch command. Use `-nodesktop` instead, which suppresses the GUI but keeps the JVM alive.

### Starting MATLAB Without the Startup Script

Simply opening the MATLAB desktop and typing commands does not automatically share the session unless you explicitly call `matlabmcp.start`. Many users assume the repository acts as a background service, but it requires an explicit startup routine.

**Fix:** Always launch MATLAB with the `-r "matlabmcp.start; pause(inf)"` argument, or manually execute `matlabmcp.start` in the Command Window and keep MATLAB open.

### Port Conflicts

If another application (e.g., a previous MATLAB instance that crashed) holds port 5000, the HTTP server in `start.m` will fail to bind. Depending on the implementation, it may exit or start but never register the session.

**Fix:** Check for listeners with `lsof -i :5000` (Linux/macOS) or `netstat -ano | findstr :5000` (Windows). Kill the offending process or change `MATLABMCP_PORT`.

### Version Mismatch Between Client and MATLAB

The Engine API is tied to a specific MATLAB release. If the Python client was built against R2023b but the running MATLAB is R2022a, the `shareEngine` call may succeed, yet the client will be unable to attach, resulting in the same “No shared sessions” message because the client filters out incompatible engines.

**Fix:** Align versions. Rebuild the Engine for Python against the target MATLAB release and reinstall the client library.

## Quick Diagnostic Checklist

- [ ] MATLAB Engine for Python is installed (`import matlab.engine` succeeds).
- [ ] MATLAB version matches the Python client’s build version.
- [ ] MATLAB launched **without** `-nojvm` and **with** `-r "matlabmcp.start; pause(inf)"`.
- [ ] Environment variable `MATLABMCP_PORT` is set (or port 5000 is free).
- [ ] `curl http://127.0.0.1:5000/sessions` returns a non‑empty JSON array.
- [ ] No firewall rules block localhost traffic on the chosen port.

## Summary

- The **"No shared MATLAB sessions found"** error is a server‑side (MATLAB) configuration issue, not a client bug.
- **MATLAB must be started with the `matlabmcp.start` script**, which registers the engine via `matlab.engine.shareEngine('MATLABMCP')` and spins up the HTTP advertizer on `localhost:5000` (or `MATLABMCP_PORT`).
- **Never use the `-nojvm` flag**; the Engine API requires the Java Virtual Machine.
- **Verify reachability** with `curl` before running the Python client; an empty JSON response means the sharing handshake failed.
- **Align MATLAB and Python client versions** to avoid silent filtering of incompatible sessions.

## Frequently Asked Questions

### Do I need a MATLAB license to use matlabmcp?

Yes. `matlabmcp` is a thin wrapper around the official MATLAB Engine for Python, which requires a valid MATLAB license. The Engine checks out a license seat when `matlab.engine.shareEngine` is called, and the seat remains held until the MATLAB process exits or `unshareEngine` is invoked.

### Can I run the MATLAB side on a remote machine?

The default configuration binds the HTTP advertizer to `localhost` (127.0.0.1) for security. To run MATLAB on a remote host, you must either:
- Set the environment variable `MATLABMCP_HOST` to `0.0.0.0` before launching MATLAB (if the repository supports it), or
- Use an SSH tunnel to forward the remote port to your local machine: `ssh -L 5000:remote_host:5000 user@remote_host`.

Consult [[`Docs/Working.md`](https://github.com/jigarbhoye04/matlabmcp/blob/main/Docs/Working.md)](https://github.com/jigarbhoye04/matlabmcp/blob/main/Docs/Working.md) for the latest networking options.

### Why does the error persist even after I start MATLAB?

If you started MATLAB interactively (e.g., clicked the desktop icon) but did **not** execute `matlabmcp.start`, the Engine is running but has not been shared. The HTTP advertizer only starts when `start.m` runs. Always launch MATLAB with the `-r "matlabmcp.start; pause(inf)"` flag, or manually type `matlabmcp.start` in the Command Window and leave MATLAB open.

### Is there a way to auto-start the shared session when MATLAB launches?

Yes. You can add the startup command to your MATLAB `startup.m` file (located in the userpath). Add the line:

```matlab
matlabmcp.start;

```

Then, whenever MATLAB starts—whether from the desktop or the command line—the shared session will be advertised automatically. Note that if you use `startup.m`, you do not need the `-r` flag, but you must still ensure MATLAB does not exit immediately (e.g., by running a script that ends with `pause(inf)` or by keeping the desktop open).