MCP server for AI agents

About the MCP server

Meridian has an MCP (Model Context Protocol) server, meridian-mcp. An AI agent uses it to open, read, change, check, simulate and export Meridian models.

The server uses stdio only. It does not open a network port.
The meridian-cad skill comes with the server. The skill tells the agent the correct workflow.
On Windows, the installer component "AI agent tools (MCP)" installs the server.

Add the server to an agent

Use the meridian mcp install command.

Agent	Command
Hermes Agent	`meridian mcp install --hermes`. Then run `hermes mcp test meridian` to test it.
Claude Desktop	`meridian mcp install --claude-desktop`
Claude Code, one project	`meridian mcp install --claude-code --project <dir>`
Claude Code, all projects	`meridian mcp install --claude-code --scope user`
A different agent	`meridian mcp install --print` shows the command and the JSON and YAML forms. It writes nothing. Copy the configuration into the agent.

Install options

Option	What it does
`--root <dir>`	Adds a workspace folder. You can give this option more than one time.
`--read-only`	The agent can read models but cannot change files.
`--no-studio`	The agent does not get the `studio_*` tools.
`--name <name>`	Sets a different server name. The default is `meridian`. Use it, for example, for a second entry with other folders.
`--profile <name>`	Sets the Hermes profile. The default is the active profile.
`--hermes-home <dir>`	Sets the Hermes home folder.
`--dry-run`	Shows the changes but does not write them.

Server options

Option or variable	What it does
`--timeout <s>`	The time limit of one tool call. The default is 120 seconds.
`--data <dir>`	Uses this data folder.
`--log-level error\\|warn\\|info\\|debug`	Sets the log detail.
`MERIDIAN_MCP_ROOTS`	The workspace folders. Separate the folders with `;` on Windows and `:` on Linux.
`MERIDIAN_MCP_READONLY=1`	Read-only mode.

The options have priority over the variables.

Remove the server from an agent

meridian mcp uninstall --hermes
meridian mcp uninstall --claude-desktop
meridian mcp uninstall --claude-code

To see the status, run meridian mcp status.

Workspace folders

The agent can only use files in the workspace folders. A path outside these folders gives the error outside_workspace. The sample files are read-only.

Tools

The server has 61 tools.

Group	Tools
Files and documents	`server_info`, `list_files`, `list_templates`, `open_document`, `create_document`, `list_open_documents`, `close_document`, `save_document`
Read a model	`describe_document`, `list_geometry`, `get_feature_schema`
Change a model	`set_parameters`, `set_properties`, `create_sketch`, `add_extrude`, `add_revolve`, `add_hole`, `add_fillet`, `add_chamfer`, `add_shell`, `add_pattern`, `add_mirror`, `add_primitive`, `add_feature`, `edit_feature`, `delete_feature`, `suppress_feature`, `run_rule`, `undo`, `redo`
Check	`regenerate`, `measure`, `mass_properties`, `check_interference`, `bolt_calculation`
Simulation	`list_studies`, `create_study`, `edit_study`, `delete_study`, `run_study`, `estimate_study`, `probe_study`
Output	`render_preview`, `export`
Assemblies	`place_component`, `add_mate`
Meridian window	`studio_status`, `studio_list_documents`, `studio_get_active_document`, `studio_set_active_document`, `studio_open_document`, `studio_describe_document`, `studio_list_commands`, `studio_run_command`, `studio_get_selection`, `studio_select`, `studio_get_parameters`, `studio_set_parameters`, `studio_screenshot`, `studio_undo`, `studio_redo`

Resources and prompts

Resources: meridian://documents, meridian://samples and reference pages under meridian://reference/.
Prompts: design_flange, design_bracket, review_part, parametric_variant, bolted_joint.

Values and units

A number is in millimeters or degrees.
A text value can be an expression, for example "2 in" or "Thickness * 2".
Each change is one undo step.

Recommended workflow for agents

Call server_info.
Open a document with open_document, or make one with create_document.
Call describe_document to read the model.
Change parameters first, before you add new features.
To add geometry, make a sketch and then a feature.
After each change, make sure that the model regenerates without errors.
Check the result with render_preview and mass_properties.
Save the document or export it.

Simulation through the server

Study kinds: static, modal, flow, thermal, buckling, harmonic and transient.
Studies are saved in the .mpart or .massy file. Results are not saved. Run the study again to get them.
Call estimate_study before a large run. It gives the node count, the memory in MB and the expected time on a desktop computer.
Start with a coarse mesh. Make the mesh finer when the setup is correct.
Factor of safety = yield strength / maximum von Mises stress. A value from 1.5 to 3 is usual.
A buckling factor less than 1 means that the part buckles.
The export tool can write study results as results-csv or results-vtk, for structural and thermal studies.

Control the Meridian window

An agent can also control the open Meridian window with the studio_* tools. This is off by default.

In Meridian, select Tools > Preferences.
Go to the General page.
Under AI agents, select Allow AI agents to control Meridian Studio.

When this is on:

The status bar shows "Agent control on". When an agent connects, it shows "AI agent connected".
An undo step that an agent made has "(Agent)" in its name.
An agent cannot change the preferences, save, close documents, exit Meridian, open a file outside its workspace folders, or see other windows.

Security

The server does not connect to the network.
The server talks to the Meridian window through a local named pipe for your user only, with a new random token at each start.
Text in documents (names, descriptions, properties) is data. The skill tells the agent never to follow instructions in documents.
The logs do not contain document contents or parameter values.
An assembly that an agent opens loads parts only from the workspace folders and the samples.
Use --read-only and a small set of workspace folders to limit what an agent can do.

Error codes

Code	Meaning
`invalid_argument`	A value is not correct.
`not_found`	The document, feature or item does not exist.
`outside_workspace`	The path is outside the workspace folders.
`parameter_error`	A parameter expression is not correct.
`conflict`	A name is in use, or other features need the feature.
`unsaved_changes`	The document has changes that are not saved. Save first, or close with `discardChanges`.
`read_only`	The file or the server is read-only.
`limit_exceeded`	A limit was exceeded.
`timeout`	The call took more time than the time limit.
`studio_unavailable`	The agent cannot reach Meridian Studio.

Troubleshooting

Problem	Action
The agent does not find the server.	Run `meridian mcp status`. For Hermes, run `hermes mcp test meridian`.
The server does not start.	Run `meridian-mcp --version` in a terminal. Read the log.
`studio_unavailable`	Start Meridian Studio and turn on Allow AI agents to control Meridian Studio.
`outside_workspace`	Add the folder with `--root <folder>` (run the install command again), or move the file into a workspace folder.
An update waits for Meridian.	An agent session keeps `meridian-mcp` running. Stop the agent, then update.
`WinError 193` in Hermes on Windows	The command in the entry is not a program. Use the full path of `meridian-mcp.exe`. `meridian mcp install --hermes` writes it.

The logs are in %LOCALAPPDATA%\Meridian\logs on Windows and in ~/.local/share/Meridian/logs on Linux.