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

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) 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 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) 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) 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:

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

Verify the installation by importing the engine inside 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:

disp(version)

And on the Python side:

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:

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:

matlabmcp.start

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

What matlabmcp.start Does (Inside start.m)

The 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:

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:

curl http://127.0.0.1:5000/sessions

You should receive JSON similar to:

{"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) 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:

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).

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