Tools and capabilities#

Tool surface#

PyFluent-MCP exposes 22 tools organized into 6 groups:

Group	Tools
Connection & session	`connect`, `disconnect`, `session_status`, `solver_status`
Schema discovery	`find_api`, `get_help`, `get_state`, `get_targeted_context`
Named objects	`list_named_objects`, `find_named_object`, `select_named_objects`
Execution & validation	`run_code`, `validate_code`
Reporting & inspection	`summarize_setup`, `simulation_report`, `screenshot`
Domain tools	`mesh_quality`, `list_fields`, `compare_files`

Live versus offline tools#

Offline-capable tools work without a live Fluent session:

find_api and get_help search the bundled settings schema.
validate_code performs an AST pre-check only.

Live-session tools require PyFluent and a connected Fluent solver:

connect, disconnect, session_status, solver_status
get_state, get_targeted_context, named-object tools
run_code, summarize_setup, simulation_report, screenshot
mesh_quality, list_fields, compare_files

Using the tools#

Discover-validate-execute loop#

For most setup tasks, follow this pattern:

Discover: find_api("turbulence model") or get_state("setup.general").
Validate: validate_code(python_snippet).
Execute: run_code(python_snippet).
Verify: summarize_setup() or simulation_report().

Connection management#

Use connect to launch a new Fluent session or attach to an existing one:

“Connect to Fluent and launch a new solver session.”

“Connect to Fluent on 192.168.1.100 port 18500.”

Use session_status to check whether a session is active and disconnect to release it.

Schema discovery#

Use find_api for ranked path search over the settings tree:

“Find API paths related to boundary condition velocity inlet.”

Use get_state to read live values and list_named_objects to enumerate named collections (boundary conditions, cell zones, materials, and so on).

Code execution#

run_code executes sandboxed PyFluent Python in a persistent REPL namespace. This tool mutates the live solver. Always prefer validate_code first for untrusted code.

validate_code performs an AST and signature pre-check without execution.

Domain tools#

mesh_quality returns live skewness, orthogonal quality, and aspect-ratio metrics. Route all “show mesh quality / skewness / check mesh” intents here.

list_fields enumerates scalar/vector fields available in the loaded case.

compare_files diffs two case/mesh files in separate ephemeral headless sessions without touching the live workspace session. Requires the file-probe extra for .h5/.cas.h5 files.

Workflow examples#

Load a case and inspect setup#

connect launches or attaches to Fluent.
run_code loads a case file.
summarize_setup gets a compact digest of models, BCs, and materials.
mesh_quality checks mesh quality metrics.

Generate and apply a settings change#

find_api("under-relaxation pressure") discovers the active path family.
get_state("solution.controls") reads the live URF configuration.
validate_code then run_code applies the change.

Compare two case files#

compare_files(path_a="old.cas.h5", path_b="new.cas.h5") returns a structured diff in separate headless sessions.

Result models and errors#

Tool return types#

Model	Returned by
`ConnectResult`	`connect`
`RunCodeResult`	`run_code`

Configuration is loaded from FLUIDS_MCP_* environment variables via load_config(). Use validate_config() to check the configuration at startup.

Error types#

All errors inherit from FluidsMCPError:

Error	When raised
`NotConnectedError`	A live-session tool is called with no active Fluent connection.
`BackendUnavailableError`	The requested backend kind is not registered.
`InvalidArgumentsError`	Tool arguments fail validation.
`DiscoveryError`	Schema or API discovery fails
`UpstreamError`	PyFluent or the solver returns an error.
`ConfigError`	Configuration is invalid.

Python API#

The package re-exports the server class and shared models from its top-level namespace:

from ansys.fluent.mcp import (
    SolveMCP,
    ConnectResult,
    RunCodeResult,
    FluidsMCPConfig,
    load_config,
)

Feature reference#

For full API details, including all parameters and return values, see API reference.

Best practices#

For recommendations on using PyFluent-MCP effectively, see Best practices.