Content
# Abaqus MCP
**English** | [中文](README.zh-CN.md)
This repository provides an MCP server for controlling a live Abaqus/CAE session through a local socket bridge.
This guide covers the basic Windows installation flow.
## Prerequisites
- Windows.
- A licensed Abaqus/CAE installation. Abaqus 2024 or newer is required.
- Python 3.10 or newer.
- An MCP-capable client, such as Codex.
## Compatibility Policy
This project supports **Abaqus 2024 and newer only**. Abaqus 2024 is the release
where Abaqus migrated its kernel scripting from Python 2.7 to Python 3.10.5, and
all code targets that Python 3.10 baseline or newer.
Abaqus 2023 and earlier ship a Python 2.7 kernel and are **not supported**: the
plugin relies on Python 3-only syntax and will not load under Python 2.7.
In the commands below, replace:
```text
<repo>
```
with the absolute path to this repository.
Example path format:
```text
C:\path\to\Abaqus_MCP
```
## 1. Install Python Dependencies
Open PowerShell in the repository folder:
```powershell
cd <repo>
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\python.exe -m pip install -e .
```
This creates a project-local virtual environment and installs the MCP server dependencies, including [`abqpy`](https://github.com/haiiliin/abqpy) `2024.*`. `abqpy` is the full Abaqus 2024 scripting API published as importable, typed, docstring-carrying stubs. The server imports it offline (with `ABQPY_SKIP_ABAQUS=1`, so it never tries to launch CAE) purely to introspect API signatures and parameter/return documentation — see the `describe_abaqus_api` tool.
## 2. Set Environment Variables
Set Windows user environment variables:
```powershell
[Environment]::SetEnvironmentVariable("ABAQUS_MCP_HOME", "<repo>\kernel", "User")
[Environment]::SetEnvironmentVariable("ABAQUS_MCP_HOST", "127.0.0.1", "User")
[Environment]::SetEnvironmentVariable("ABAQUS_MCP_PORT", "48152", "User")
```
`ABAQUS_MCP_HOME` must point to the `kernel` folder, which contains `abaqus_mcp_plugin.py` and `templates/`.
Restart Abaqus/CAE after setting these variables.
## 3. Install the Abaqus Plug-in Loader
Copy the Abaqus menu loader into the Abaqus user plug-in directory:
```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\abaqus_plugins" | Out-Null
Copy-Item -Recurse -Force `
"<repo>\abaqus_plugins\mcp_control" `
"$env:USERPROFILE\abaqus_plugins\mcp_control"
```
Restart Abaqus/CAE. The following menu should appear:
```text
Plug-ins > Abaqus MCP
```
## 4. Start the Socket Bridge
In Abaqus/CAE, click:
```text
Plug-ins > Abaqus MCP > Start Socket Bridge
```
Verify that the bridge is listening:
```powershell
Test-NetConnection -ComputerName 127.0.0.1 -Port 48152
```
Expected result:
```text
TcpTestSucceeded : True
```
## 5. Configure Codex
Add the MCP server to your Codex `config.toml`:
```toml
[mcp_servers.abaqus-mcp-server]
command = "<repo>\\.venv\\Scripts\\python.exe"
args = ["<repo>\\server\\mcp_server.py"]
cwd = "<repo>"
[mcp_servers.abaqus-mcp-server.env]
ABAQUS_MCP_HOST = "127.0.0.1"
ABAQUS_MCP_PORT = "48152"
ABAQUS_MCP_TIMEOUT = "60"
ABAQUS_MCP_HOME = "<repo>\\kernel"
```
Restart Codex after editing the configuration.
## 6. Verify the Connection
With Abaqus/CAE open and the socket bridge started, call one of these MCP tools from your client:
```text
ping
check_abaqus_connection
```
A successful response means the MCP client can communicate with the live Abaqus/CAE session.
## Troubleshooting
If the MCP client reports that it cannot connect to `127.0.0.1:48152`, start the bridge again from:
```text
Plug-ins > Abaqus MCP > Start Socket Bridge
```
If the Abaqus MCP menu does not appear, check that:
- `mcp_control` was copied into `%USERPROFILE%\abaqus_plugins`.
- `ABAQUS_MCP_HOME` points to the `kernel` folder inside the repository.
- Abaqus/CAE was restarted after setting the environment variables.
