find_matlab() vs connect_matlab() vs shareEngine: MATLAB Engine API Functions Explained

TLDR: In the MatlabMCP integration, matlab.engine.shareEngine prepares a MATLAB session for external access from within MATLAB, find_matlab() discovers these shared sessions from Python, and connect_matlab() establishes the actual communication channel, returning an engine object for executing code.

The MatlabMCP repository bridges large language model tools with live MATLAB environments using the MATLAB Engine API for Python. Understanding the differences between find_matlab(), connect_matlab(), and shareEngine is critical for troubleshooting connection issues and understanding the architectural flow. These three functions operate on different sides of the Python-MATLAB boundary and serve distinct purposes in the discovery and connection pipeline.

The Three Functions Explained

matlab.engine.shareEngine (MATLAB-Side Setup)

matlab.engine.shareEngine runs inside the MATLAB desktop or console, not in Python. This command marks the current MATLAB process as shareable by creating a named pipe or socket that external programs can locate.

Before starting the MatlabMCP server, users must execute this command in their MATLAB session:

matlab.engine.shareEngine

According to the repository's README.md (lines 47-50), this step is mandatory. The command returns true or 1 if the session is already shared, which you can verify using matlab.engine.isEngineShared.

matlab.engine.find_matlab() (Python-Side Discovery)

matlab.engine.find_matlab() operates on the Python side to scan the local machine for MATLAB sessions that have been shared. It returns a list of session name strings (e.g., ['MATLAB_1', 'MATLAB_2']) that can be passed to connect_matlab().

In main.py at line 27, MatlabMCP uses this function to discover available sessions:

import matlab.engine

names = matlab.engine.find_matlab()  # Returns ['MATLAB_1', ...]

if not names:
    # Handle error: no shared sessions found

    pass

If no shared sessions exist, the function returns an empty list [], which the code checks to abort with a clear error message.

matlab.engine.connect_matlab() (Python-Side Connection)

matlab.engine.connect_matlab(session_name) opens a communication channel to a specific shared MATLAB session identified by the session_name parameter obtained from find_matlab(). It returns an engine object (eng) that enables Python to call MATLAB functions, access the workspace, and execute code.

In main.py at line 39, the implementation connects to the first discovered session:

eng = matlab.engine.connect_matlab(names[0])

This engine object exposes methods like eng.evalc() and eng.workspace, which MatlabMCP tools use to execute MATLAB code asynchronously via asyncio.to_thread(). If the connection fails (e.g., the session vanished), it raises matlab.engine.EngineError.

How the Functions Work Together in MatlabMCP

These functions operate in a strict sequence to establish the Python-MATLAB bridge:

1. User prepares MATLAB: Execute matlab.engine.shareEngine in MATLAB to publish the session name to the operating system.
2. Python discovers sessions: The MatlabMCP server calls find_matlab() in main.py (line 27) to retrieve the list of published session names.
3. Python connects: The server selects the first available name and calls connect_matlab() in main.py (line 39) to obtain the engine object.
4. Tool execution: Subsequent MCP tool implementations (runMatlabCode, getVariable, etc.) use this eng object to issue non-blocking calls to the shared MATLAB instance.

Error Handling and Return Values

Each function handles failures differently based on its operating context:

• shareEngine: Returns a boolean indicating if the session was already shared. Throws a MATLAB error if the Engine API is missing.
• find_matlab(): Returns an empty list [] when no shared sessions exist. The MatlabMCP server explicitly checks if not names: to provide user-friendly error messaging.
• connect_matlab(): Raises matlab.engine.EngineError on connection failure. The server catches this exception and exits with diagnostic information.

Summary

• matlab.engine.shareEngine is a MATLAB command that makes a session discoverable by external processes.
• matlab.engine.find_matlab() is a Python function that scans for and lists all shared MATLAB session names.
• matlab.engine.connect_matlab() is a Python function that attaches to a specific shared session and returns an executable engine object.
• MatlabMCP relies on this sequence: shareEngine → find_matlab → connect_matlab, implemented in main.py and documented in README.md.

Frequently Asked Questions

What happens if I don't run shareEngine before starting MatlabMCP?

The Python server will call find_matlab() and receive an empty list, causing the application to abort with an error indicating no shared MATLAB sessions were found. You must execute matlab.engine.shareEngine in your MATLAB console first.

Can I connect to multiple MATLAB sessions simultaneously?

While find_matlab() returns a list of all shared sessions, the current MatlabMCP implementation in main.py connects only to the first available session (names[0]). You could modify the code to spawn multiple engine objects by calling connect_matlab() with different session names from the list.

Why does find_matlab() return an empty list even when MATLAB is running?

MATLAB must be explicitly shared using matlab.engine.shareEngine. Simply having MATLAB open does not make it discoverable. Additionally, permission issues or firewall restrictions on the named pipe/socket can prevent the session from appearing in the scan results.

Is matlab.engine.shareEngine required for every new MATLAB session?

Yes. Each MATLAB process must independently run matlab.engine.shareEngine to become visible to Python clients. If you restart MATLAB, you must re-run this command before the MatlabMCP server can reconnect.

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