# Abaqus MCP Server

[中文说明](README.zh-CN.md)

A clean, GitHub-ready Model Context Protocol (MCP) package for controlling a live Abaqus/CAE session through Kimi, Claude, or Codex.

The package consists of:

- `mcp_server.py` — a stdio MCP server that exposes Abaqus-specific tools.
- `abaqus_mcp_plugin.py` — a low-latency TCP socket bridge that runs inside Abaqus/CAE.
- `abaqus_plugins/mcp_control/` — an optional Abaqus/CAE GUI plugin loader.
- `setup.ps1` — a one-click Windows installer that copies the package, creates a virtual environment, installs dependencies, and registers the MCP server with Kimi and Claude/Codex.
- `install_mcp_config.py` — a JSON merge helper that preserves unrelated MCP client settings.

## Architecture

```text
MCP client (Kimi / Claude / Codex)
  <stdio MCP>
mcp_server.py
  <local TCP JSON, default 127.0.0.1:48152>
Abaqus/CAE GUI bridge
  <AFX timeout dispatcher + sendCommand>
Abaqus kernel
```

The bridge executes Python on the Abaqus GUI thread and returns structured results, which avoids file-based polling and keeps interactive commands fast.

## Prerequisites

- Windows 10/11.
- Abaqus/CAE 2019 or newer.
- Python 3.10+ (Python 3.14 is known to work; Abaqus ships its own Python, but this MCP server uses a normal system Python).
- The `mcp` package (`>=1.0,<2`). The installer handles this automatically.
- Optional: Intel Fortran compiler if you intend to run user subroutines with Abaqus/Standard or Abaqus/Explicit.

## Quick Install

Open a PowerShell terminal in this directory and run:

```powershell
.\setup.ps1
```

The installer will:

1. Copy the package source to `C:\Users\<username>\.abaqus-mcp`.
2. Create a virtual environment at `C:\Users\<username>\.abaqus-mcp\.venv` and install the package in editable mode.
3. Copy `abaqus_v6.env.example` to `C:\Users\<username>\abaqus_v6.env` if one does not already exist.
4. Copy `abaqus_plugins\mcp_control` to `C:\Users\<username>\abaqus_plugins\mcp_control`.
5. Register the MCP server in `C:\Users\<username>\.kimi\mcp.json` and `C:\Users\<username>\.claude\settings.json`.

To skip the MCP client registration step, run:

```powershell
.\setup.ps1 -SkipMcpRegistration
```

## How to Start the Abaqus GUI Bridge

1. Start Abaqus/CAE.
2. Choose **Plug-ins > Abaqus MCP > Start Socket Bridge** from the menu bar.
3. The message area will confirm the bridge is listening on `127.0.0.1:48152`.
4. In your MCP client, start the `abaqus-mcp-server` server.

If you want the menu to appear automatically on every Abaqus/CAE startup, make sure `C:\Users\<username>\abaqus_v6.env` contains the startup hook from `abaqus_v6.env.example` and that `ABAQUS_MCP_HOME` points to `C:\Users\<username>\.abaqus-mcp`.

## MCP Tools

| Tool | Description |
|------|-------------|
| `ping` | Verify the socket bridge is alive and return live session telemetry. |
| `check_abaqus_connection` | Human-readable connection status. |
| `run_python` | Execute Abaqus Python inside the live CAE kernel with structured return values and diagnostics. |
| `execute_script` | Compatibility wrapper around `run_python`. |
| `set_workdir` | Change the Abaqus working directory before creating or submitting jobs. |
| `get_model_info` | Inspect models, parts, materials, steps, loads, BCs, interactions, jobs, and viewports. |
| `list_jobs` | List jobs defined in the current CAE session. |
| `submit_job` | Submit an existing job and wait for it to finish. |
| `monitor_job_status` | Tail `.sta` / `.msg` diagnostics or list job status. |
| `inspect_odb` | Inspect an ODB file's metadata, steps, frames, and available outputs. |
| `get_odb_info` | Compatibility wrapper around `inspect_odb`. |
| `capture_viewport` | Capture the current viewport image as structured base64 data. |
| `get_viewport_image` | Compatibility wrapper returning a data URI. |

## Example Usage Prompts

After starting the bridge, you can ask the MCP client:

- "Ping the Abaqus bridge and tell me what model is open."
- "Run a short Python snippet to list all parts in the current model."
- "Set the Abaqus working directory to `D:\\abaqus_jobs\\run_001`."
- "Submit the job named `Job-1` and monitor its status."
- "Inspect the ODB at `D:\\abaqus_jobs\\run_001\\Job-1.odb` and report the available field outputs."
- "Capture the current viewport and describe what you see."

## Boundaries and Limitations

- **Abaqus/CAE must be running.** The MCP server controls a live CAE session through the socket bridge; it cannot start Abaqus/CAE headlessly for live control.
- **Start the bridge manually.** Before using the MCP tools, choose **Plug-ins > Abaqus MCP > Start Socket Bridge** inside Abaqus/CAE.
- **Localhost only.** The bridge binds to `127.0.0.1:48152` by default. It is not designed for remote or multi-user access.
- **No standalone noGUI workflow.** This package does not include text-to-CAE generation or batch noGUI/viewer-only pipelines. `noGUI` batch jobs should be launched through normal Abaqus command-line scripts outside this MCP server.
- **Large ODBs may be slow.** ODB inspection and viewport capture send data over the local TCP bridge; very large files can take time and are bounded by `ABAQUS_MCP_MAX_MESSAGE_BYTES` (default 32 MB).
- **No FEA solver bundled.** The package only automates Abaqus/CAE; you must have a licensed Abaqus installation.

## Manual Configuration

If you installed without `-SkipMcpRegistration`, the server is already registered. Otherwise, add it manually:

```json
{
  "mcpServers": {
    "abaqus-mcp-server": {
      "command": "C:\\Users\\<username>\\.abaqus-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\<username>\\.abaqus-mcp\\mcp_server.py"],
      "cwd": "C:\\Users\\<username>\\.abaqus-mcp",
      "env": {
        "ABAQUS_MCP_HOST": "127.0.0.1",
        "ABAQUS_MCP_PORT": "48152",
        "ABAQUS_MCP_TIMEOUT": "60",
        "ABAQUS_MCP_HOME": "C:\\Users\\<username>\\.abaqus-mcp"
      }
    }
  }
}
```

## License

See [LICENSE](./LICENSE) and [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).