The tools.py module

Summary

Functions

check_mechanical_status	Check the status of Mechanical initialization.
check_mechanical_installed	Check if Mechanical is installed on the system.
run_python_script	Execute a Python script inside Mechanical.
launch_mechanical	Launch a new Mechanical instance.
connect_to_mechanical	Connect to an existing Mechanical instance.
disconnect_from_mechanical	Disconnect from the connected Mechanical instance.
list_mechanical_instances	List all Mechanical instances running on the local machine.
list_files	List files in the Mechanical working directory.
upload_file	Upload a file to the Mechanical instance.
download_file	Download a file from the Mechanical instance.
clear_mechanical	Clear the Mechanical database.
mechanical_working_directory	Return the working directory of the connected Mechanical instance.
get_model_info	Get information about the current model in Mechanical.
screenshot	Capture a screenshot of the current Mechanical view.
run_python_code	Execute Python code in the persistent Python session for data processing.
create_custom_plot	Create a custom plot using Matplotlib in the persistent Python session.
save_project	Save the current Mechanical project.
open_project	Open an existing Mechanical project file.
solve_analysis	Solve the specified analysis in Mechanical.
export_results	Export results from the solved analysis.
get_mechanical_logs	Return recent log entries from the connected Mechanical instance.

Attributes

logger

Constants

REQUIRES_MECHANICAL_TAG

Description

List of tools in PyMechanical-MCP.

Module detail

tools.check_mechanical_status(ctx: fastmcp.server.Context) → str

Check the status of Mechanical initialization.

This tool retrieves comprehensive information from the connected Mechanical instance including version, project directory, and connection status.

Parameters:

ctxContext

MCP context containing the server session and application context.

Returns:

str

JSON string containing comprehensive Mechanical status information including:

• connection: Basic connection information (version, project_directory, is_alive)

• product_info: Product version and build information

Returns an error message if Mechanical is not available or has exited.

tools.check_mechanical_installed(ctx: fastmcp.server.Context) → str

Check if Mechanical is installed on the system.

This tool checks whether Ansys Mechanical is properly installed and available on the system by inspecting standard installation paths.

Note

When PyMechanical-MCP runs inside a Docker container, the host filesystem is not accessible. In this case, the tool probes the configured gRPC endpoint instead and reports whether a Mechanical server is reachable.

Returns:

str

Status message indicating whether Mechanical is installed or reachable.

tools.run_python_script(ctx: fastmcp.server.Context, script: str | None = None, file_path: str | None = None) → str

Execute a Python script inside Mechanical.

This tool runs a Python script block inside the connected Mechanical instance using Mechanical’s scripting API. The script has access to Mechanical’s ExtAPI, DataModel, Model, Tree, and Graphics entry points.

Provide either an inline script string or a file_path pointing to a local Python file. When file_path is given, its contents are read and executed inside Mechanical.

Parameters:

ctxContext

MCP context containing the server session and application context.

scriptstr, optional

The Python script to execute inside Mechanical. Required when file_path is not provided.

file_pathstr, optional

Path to a local Python script file whose contents are executed inside Mechanical. Takes precedence over script when both are provided.

Returns:

str

Script execution result. Returns the string value of the last executed statement, or an empty string if the value cannot be returned as a string.

async tools.launch_mechanical(ctx: fastmcp.server.Context, exec_file: str | None = None, port: int | None = None, batch: bool = True, version: str | None = None, transport_mode: str | None = None) → str

Launch a new Mechanical instance.

This tool starts a new Mechanical instance using PyMechanical’s launch_mechanical function. The launched instance will be automatically connected and stored in the context for subsequent operations. Once connected, additional tools become available to interact with it (including run_python_script, screenshot, and save_project).

Parameters:

ctxContext

MCP context containing the server session and application context.

exec_filestr, default: None

path to the Mechanical executable. If None, PyMechanical attempts to find the executable automatically.

portint, default: None

gRPC port for Mechanical to listen on. If None, 10000 is used.

batchbool, default: True

Whether to launch Mechanical in batch mode.

versionstr, default: None

Mechanical version to run (such as “252” for 2025 R2). If None, the latest installed version is used.

transport_modestr, default: None

gRPC transport mode for the launched instance. Options are auto, insecure, mtls, and wnua. When None or auto, PyMechanical applies the platform default.

Returns:

str

Launch status message with Mechanical version and connection information.

async tools.connect_to_mechanical(ctx: fastmcp.server.Context, port: int = 10000, ip: str = '127.0.0.1', transport_mode: str | None = None) → str

Connect to an existing Mechanical instance.

This tool establishes a connection to a running Mechanical instance using the provided port and IP address. The connection is stored for subsequent operations and can be closed using the disconnect_from_mechanical tool. Once connected, additional tools become available to interact with it (including run_python_script, screenshot, and save_project).

Parameters:

ctxContext

MCP context containing the server session and application context.

portint, default: 10000

gRPC port where Mechanical is listening.

ipstr, default: “127.0.0.1”

IP address where Mechanical is running.

transport_modestr, default: None

gRPC transport mode. Options are "auto", "insecure", "mtls", and "wnua". When None or "auto", the mode is determined automatically. On Windows, it defers to PyMechanical’s default ( "wnua"). On Linux/Docker, it uses "mtls" if certificates are found. Otherwise it uses "insecure".

Returns:

str

Connection status message with Mechanical version information.

async tools.disconnect_from_mechanical(ctx: fastmcp.server.Context) → str

Disconnect from the connected Mechanical instance.

This tool closes the connection to the Mechanical instance and releases the associated resources.

Parameters:

ctxContext

MCP context containing the server session and application context.

Returns:

str

Disconnection status message.

tools.list_mechanical_instances() → str

List all Mechanical instances running on the local machine.

This tool discovers Mechanical instances running on the machine by scanning for active gRPC servers and their associated metadata.

Note

When the MCP server runs inside a Docker container, host process scanning is not available. In this case, the tool probes the configured gRPC endpoint and reports its reachability.

Returns:

str

Formatted table of Mechanical instances, or reachability status when running in Docker.

tools.list_files(ctx: fastmcp.server.Context) → str

List files in the Mechanical working directory.

This tool lists all files in the working directory of the connected Mechanical instance.

Parameters:

ctxContext

MCP context containing the server session and application context.

Returns:

str

List of files in the working directory.

tools.upload_file(ctx: fastmcp.server.Context, file_path: str) → str

Upload a file to the Mechanical instance.

This tool uploads a local file to the Mechanical instance’s working directory.

Parameters:

ctxContext

MCP context containing the server session and application context.

file_pathstr

Path to the local file to upload.

Returns:

str

Upload status message.

tools.download_file(ctx: fastmcp.server.Context, file_name: str, target_dir: str | None = None) → str

Download a file from the Mechanical instance.

This tool downloads a file from the Mechanical instance’s working directory to the local filesystem.

Parameters:

ctxContext

MCP context containing the server session and application context.

file_namestr

Name of the file to download from the Mechanical working directory.

target_dirstr, optional

Local directory to save the downloaded file. If None, the current directory is used.

Returns:

str

Download status message with local file path.

tools.clear_mechanical(ctx: fastmcp.server.Context) → str

Clear the Mechanical database.

This tool clears the current database in the Mechanical instance, providing a fresh start for a new analysis.

Parameters:

ctxContext

MCP context containing the server session and application context.

Returns:

str

Clear status message.

tools.mechanical_working_directory() → str

Return the working directory of the connected Mechanical instance.

This resource provides the absolute path to the active project directory used by the connected Mechanical instance. The value is resolved lazily each time the resource is read.

Returns:

str

Absolute path to the Mechanical project directory, or a message indicating that Mechanical is not connected.

tools.get_model_info(ctx: fastmcp.server.Context) → str

Get information about the current model in Mechanical.

This tool retrieves information about the current model including geometry, mesh, and analysis settings by executing a script inside Mechanical.

Parameters:

ctxContext

MCP context containing the server session and application context.

Returns:

str

JSON string containing model information.

tools.screenshot(ctx: fastmcp.server.Context, view_type: str = 'model') → list[mcp.types.TextContent | mcp.types.ImageContent]

Capture a screenshot of the current Mechanical view.

This tool captures the current graphics view from Mechanical as an image. It can capture model views, mesh views, or result contour plots.

Parameters:

ctxContext

MCP context containing the server session and application context.

view_typestr, default: "model"

Type of view to capture. Options are "model", "mesh", and "result".

Returns:

list[TextContent | ImageContent]

A list containing:

• TextContent with the screenshot file path

• ImageContent with the base64-encoded image data

tools.run_python_code(ctx: fastmcp.server.Context, code: str, timeout: int = 60) → str

Execute Python code in the persistent Python session for data processing.

IMPORTANT: This tool runs in a separate Python process and does NOT have access to the Mechanical gRPC connection. Use this tool for:

• Custom data processing and analysis (NumPy, Pandas, and SciPy)

• Creating Matplotlib plots and visualizations

• Postprocessing results exported from Mechanical

• General Python computations

For code that needs to run inside Mechanical (such as IronPython with ExtAPI or Model), use the ‘run_python_script’ tool instead.

Parameters:

ctxContext

MCP context containing the server session and application context.

codestr

Python code to execute. You should use standard Python libraries. This tool does NOT have access to Mechanical’s ExtAPI, Model, or other internal objects.

timeoutint, default: 60

Maximum time in seconds to allow for code execution.

Returns:

str

Execution result or error message. Returns JSON for structured output.

tools.create_custom_plot(ctx: fastmcp.server.Context, plot_code: str, plot_type: str = 'matplotlib', timeout: int = 60) → list[mcp.types.TextContent | mcp.types.ImageContent] | str

Create a custom plot using Matplotlib in the persistent Python session.

IMPORTANT: This tool runs in a separate Python process and does not have access to the Mechanical gRPC connection. Use this to:

• Visualize data that was exported/saved from Mechanical.

• Create plots from result files (such as CSV and TXT).

• Perform postprocessing visualizations.

For plots that need data directly from Mechanical, first use run_python_script to export the data to a file. Then use this tool to create the visualization.

Parameters:

ctxContext

MCP context containing the server session and application context.

plot_codestr

Python code to create the plot. You should use matplotlib.pyplot. For Matplotlib, the code should create the figure or plot but not call plt.show(). Use the save_matplotlib_plot() helper function to return the plot.

plot_typestr, default:"matplotlib"

Type of plot. Options are "matplotlib" and "pyvista".

timeoutint, default: 60

Maximum time in seconds for plot generation.

Returns:

list[TextContent | ImageContent]

A list containing:

• TextContent with the plot creation status message

• ImageContent with the base64-encoded image data if successful

Or, a JSON string with error details if failed.

tools.save_project(ctx: fastmcp.server.Context, file_path: str | None = None) → str

Save the current Mechanical project.

This tool saves the current project to disk. If file_path is provided, the project is saved to that location (Save As). Otherwise, the project is saved in place.

Parameters:

ctxContext

MCP context containing the server session and application context.

file_pathstr, default: None

Full path for saving the project (Save As). The path should end with a .mechdb extension. If None, the project is savedin the current location.

Returns:

str

Save status message with the project file path.

tools.open_project(ctx: fastmcp.server.Context, file_path: str) → str

Open an existing Mechanical project file.

This tool opens a MECHDB project file in the connected Mechanical instance. Any unsaved work in the current project is lost.

Parameters:

ctxContext

MCP context containing the server session and application context.

file_pathstr

Full path to the MECHDB file to open.

Returns:

str

Open status message with project information.

tools.solve_analysis(ctx: fastmcp.server.Context, analysis_index: int = 0, wait: bool = True) → str

Solve the specified analysis in Mechanical.

This tool runs the solver for the specified analysis and returns the solution status. It checks for common issues and provides diagnostic information if the solve fails.

Parameters:

ctxContext

MCP context containing the server session and application context.

analysis_indexint, default: 0

Index of the analysis to solve (0-based). The default, 0, corresponds to the first analysis.

waitbool, default: True

Whether to wait for the solution to complete.

Returns:

str

JSON string with solution status, timing, and result summary.

tools.export_results(ctx: fastmcp.server.Context, result_type: str = 'all', export_format: str = 'png', output_dir: str | None = None) → str

Export results from the solved analysis.

This tool exports result images (contour plots) and/or data from the current solution. It can export individual result types or all available results at once.

Parameters:

ctxContext

MCP context containing the server session and application context.

result_typestr, default: "all"

Type of result to export. Options are "all", "deformation", "stress",

"strain", or a specific result object name.

export_formatstr, default: "png"

Export format. Use "png" for images, "txt" for text data, or "both" for images and text.

output_dirstr, default: None

Directory to save exported files. If None, uses the project directory.

Returns:

str

JSON string with export status and file paths.

tools.get_mechanical_logs(ctx: fastmcp.server.Context, source: str = 'messages', tail_lines: int = 200, contains: str | None = None, max_chars: int = 40000) → str

Return recent log entries from the connected Mechanical instance.

This tool provides visibility into Mechanical session activity by reading either the application message list or solver output log file.

Parameters:

ctxContext

MCP context containing the server session and application context.

sourcestr, optional

Log source to read. Options are:

• "messages" (default): Application messages (errors, warnings, info) from ExtAPI.Application.Messages.

• "solve_log": Raw solver transcript from solve.out in the project directory.

tail_linesint, default: 200

Number of most recent lines to return.

containsstr, optional

Case-insensitive substring filter applied to each line.

max_charsint, default: 40000

Maximum character count for the returned log text.

Returns:

str

JSON string with log metadata and selected log text.

tools.REQUIRES_MECHANICAL_TAG = 'requires_mechanical'

tools.logger