Tools reference#

This page provides reference documentation for all PyMAPDL-MCP tools.

Tool availability#

PyMAPDL-MCP dynamically enables and disables tools based on the MAPDL connection state. Tools tagged with requires_mapdl are hidden at startup and only become visible once MAPDL is connected with the connect_to_mapdl or launch_mapdl_session tool. MAPDL tools are hidden again when disconnect_from_mapdl is called.

For more information, see Tools and capabilities.

Instance management tools#

launch_mapdl_session#

Description: Launch a new MAPDL instance. This tool starts a new MAPDL process and automatically establishes a connection to it for immediate use.

Parameters:

  • exec_file (str, default: None): Path to the MAPDL executable. If None, PyMAPDL auto-detects.

  • port (int, default: None): gRPC port for MAPDL. If None, the default port is used.

  • run_location (str, default: None): Directory where MAPDL runs. If None, the temporary directory is used.

  • nproc (int, default: None): Number of processors to use. If None, MAPDL decides.

  • additional_switches (str, optional): Additional command-line switches for MAPDL.

Returns: Launch status message with MAPDL version and connection information.

Example:

result = launch_mapdl_session(
    exec_file=None,
    nproc=4,
    additional_switches="-check"
)

connect_to_mapdl#

Description: Connect to an existing running MAPDL instance.

Parameters:

  • ip (str, default: “localhost”): IP address where MAPDL is running.

  • port (int, default: 50052): gRPC port where MAPDL is listening.

Returns: Connection status message with MAPDL version information.

Example:

result = connect_to_mapdl(ip="localhost", port=50052)

list_mapdl_instances#

Description: List all MAPDL instances running on the local machine.

Returns: Formatted table with instance information (name, status, port, IP, PID, and directory).

Example:

instances = list_mapdl_instances()

check_mapdl_status#

Note

This tool is only available when connected to MAPDL.

Description: Get comprehensive MAPDL status information.

Returns: JSON string containing:

  • Connection information (version, port, IP, directory, is_alive)

  • Session information (title, jobname, routine, units, and more)

  • Geometry statistics

  • Postprocessing data

  • Mesh statistics

Example:

status = check_mapdl_status()

disconnect_from_mapdl#

Note

This tool is only available when connected to MAPDL. It is also turned off when --connect-on-startup is used.

Description: Disconnect from the currently connected MAPDL instance.

Returns: Disconnection status message.

Example:

result = disconnect_from_mapdl()

check_mapdl_installed#

Description: Check if MAPDL is installed on the system.

Returns: Status message indicating installation status.

Example:

status = check_mapdl_installed()

Command execution tools#

run_mapdl_command#

Note

This tool is only available when connected to MAPDL.

Description: Execute a single MAPDL command.

Parameters:

  • cmd (str): MAPDL command to execute.

Returns: Command execution result.

Example:

result = run_mapdl_command("FINISH")

run_multiple_commands#

Note

This tool is only available when connected to MAPDL and is turned off on AALI environments.

Description: Execute multiple MAPDL commands efficiently using batch mode.

Parameters:

  • commands (list[str]): List of MAPDL commands to execute.

Returns: Execution result with summary of commands executed.

Example:

result = run_multiple_commands([
    "FINISH",
    "/PREP7",
    "ET,1,SOLID185"
])

Python code execution tools#

run_python_code#

Note

This tool is only available when connected to MAPDL.

Description: Execute arbitrary Python code in the persistent session.

Parameters:

  • code (str): Python code to execute.

  • timeout (int, default: 60): Maximum execution time in seconds.

Returns: Execution result or error message.

Example:

code = '''
displacements = mapdl.get_array("NODE", item1="U", it1num="Y")
print(f"Max displacement: {displacements.max()}")
'''
result = run_python_code(code)

Visualization tools#

screenshot#

Note

This tool is only available when connected to MAPDL and is turned off on AALI environments.

Description: Capture a screenshot of the MAPDL graphics window.

Returns: list containing:

  • TextContent with screenshot path

  • ImageContent with base64-encoded image data

Example:

result = screenshot()

custom_plot#

Note

This tool is only available when connected to MAPDL and is turned off on AALI environments.

Description: Create a custom Matplotlib or PyVista visualization.

Parameters:

  • plot_code (str): Python code to create the plot.

  • plot_type (str, default: “matplotlib”): Type of plot to create. Options are "matplotlib" and "pyvista".

  • timeout (int, default: 60): Maximum execution time in seconds.

Returns: List containing:

  • TextContent with status message

  • ImageContent with base64-encoded image data

Example:

plot_code = '''
import matplotlib.pyplot as plt
import numpy as np

displacements = mapdl.get_array("NODE", item1="U", it1num="Y")

plt.figure(figsize=(10, 6))
plt.plot(displacements)
plt.xlabel("Node Number")
plt.ylabel("Displacement (m)")
plt.title("Custom Displacement Plot")
plt.grid(True)

result = save_matplotlib_plot(dpi=150)
print(result)
'''
result = custom_plot(plot_code, plot_type="matplotlib")

Guidelines and documentation tools#

get_guidelines_for_workflow_overview#

Description: Get general MAPDL simulation workflow guidelines.

Returns: Overview of the general simulation process.

get_guidelines_for_general_rules#

Description: Get general rules and best practices for MAPDL workflows.

Returns: General guidelines for high-quality simulations.

get_guidelines_for#

Description: Get MAPDL simulation guidelines for a specific topic using the unified tool get_guidelines_for(content).

Parameters:

  • content (str): Type of topic. Options are "workflow", "geometry", "elements", "materials", "mesh", "boundary_conditions", "solution", "postprocessing", and "general".

Returns: Guideline text for the requested topic.

Example:

result = get_guidelines_for(content="mesh")

This unified tool replaces the previous per-topic guideline tools (for example, get_guidelines_for_preprocessing_mesh) to reduce the number of registered tools and simplify client usage.

get_guidelines_for_solution_phase#

Description: Get guidelines for the solution phase.

Returns: Guidelines for configuring and running the solution.

get_guidelines_for_postprocessing_phase#

Description: Get guidelines for postprocessing results.

Returns: Guidelines for extracting and visualizing results.

Tool return values#

Most tools return structured information:

Success: Text describing the result or status.

Error: Detailed error message including:

  • Error type

  • Description of what went wrong

  • Suggested corrective action

Data: Structured data (such as JSON and arrays), depending on the tool.

Error handling#

Always check tool results for errors:

result = run_mapdl_command("INVALID_COMMAND")
# Check if result contains error information
if "error" in result.lower():
    print("Command failed:", result)
else:
    print("Command succeeded:", result)

See also#