amesim-mcp

An MCP server that exposes Siemens Simcenter Amesim's Circuit API as tools for Claude (Desktop or Code) — build circuits, wire components, set parameters, compile, run simulations, and read back results, all from a chat.

Unofficial, independent project. Not affiliated with or endorsed by Siemens. "Simcenter Amesim" is a Siemens trademark.

How it works

Amesim's Python API only exists inside AMEPython.exe, an embedded Python 3.6 interpreter shipped with Amesim. Two problems rule out just running the MCP server directly under AMEPython.exe:

1. AMEPython.exe prints an unconditional Starting Python ... banner to stdout with no way to silence it — which would corrupt the JSON-RPC stream an MCP stdio server needs.
2. AMERunSimulation (and apparently other run-management calls) hangs forever when invoked from any thread other than the process's main thread. Siemens' own scripting/python/serve_api.py example serves RPyC connections on background threads (ThreadedServer), so it hits this hang too.

So this project splits into two processes:

• MCP server (amesim_mcp/server.py) — a normal Python 3.12+ process, the one Claude talks to over stdio.
• Worker (amesim_mcp/worker_entry.py) — spawned inside AMEPython.exe, running an RPyC OneShotServer (single connection, served synchronously on the main thread — this is what avoids the hang). Its stdout/stderr (banner included) is redirected to amesim_worker.log, never touching the MCP server's own stdio.

The MCP server talks to the worker as an ordinary RPyC client over a local TCP port (default 18861).

Because AMEPython.exe's embedded interpreter has no pip/internet access, vendor/ bundles pre-built copies of the packages the worker needs (pywin32, rpyc, plumbum, adodbapi) — see NOTICE.md for their original licenses. The worker process gets vendor/ prepended to its PYTHONPATH when spawned.

Requirements

• Windows, with Simcenter Amesim installed (2021.1 and 2404 are configured by default — see below to add/change a version).
• Python 3.12+ on your normal system Python (separate from Amesim's embedded 3.6) to run the MCP server itself.
• Claude Desktop or Claude Code (or any other MCP-compatible client).

Install

git clone <this-repo-url>
cd amesim-mcp
py -3.13 -m pip install -e .

(Any Python ≥3.12 works — py -3.13 is just what was used to develop this.)

If your Amesim install lives somewhere other than C:\Program Files\Simcenter\<version>\Amesim, or you use a version other than 2021.1 / 2404, edit VERSION_DIRS in amesim_mcp/amesim_api.py:

VERSION_DIRS = {
    "2021.1": r"C:\Program Files\Simcenter\2021.1\Amesim",
    "2404": r"C:\Program Files\Simcenter\2404\Amesim",
}

Configure your MCP client

Claude Desktop — add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "amesim": {
      "command": "py",
      "args": ["-3.13", "-m", "amesim_mcp.server"]
    }
  }
}

Claude Code / other project-scoped MCP clients — copy the example and edit the path:

cp .mcp.json.example .mcp.json

{
  "mcpServers": {
    "amesim": {
      "command": "python",
      "args": ["-m", "amesim_mcp.server"],
      "cwd": "C:/path/to/amesim-mcp"
    }
  }
}

.mcp.json is machine-specific (absolute path) and is gitignored — don't commit it.

Usage

A typical session:

connect → create_circuit → add_component → change_submodel →
connect_two_ports → set_parameter_value → generate_code →
run_simulation → get_variable_values → save_circuit → disconnect

Tool	Purpose
connect(version)	Start/attach to the Amesim worker ("2021.1" or "2404")
disconnect()	Release the license token, stop the worker
status()	Connection state + Circuit API version
execute_python(code)	Run arbitrary Python in the worker's persistent namespace — ame_apy and amesim are pre-imported. Use this for anything without a dedicated tool, and to look up exact signatures with execute_python("help(ame_apy.SOME_FUNCTION)")
create_circuit(name)	Create a new circuit
open_ame_file(path)	Open an existing .ame file
save_circuit()	Save the active circuit
close_circuit(save)	Close the active circuit
add_component(icon_name, alias, x, y)	Add a component to the sketch
move_component(alias, x, y)	Move a component
rotate_component(alias, quarter_turns)	Rotate a component
flip_component(alias)	Mirror a component
remove_component(alias)	Remove a component
connect_two_ports(alias1, port1, alias2, port2)	Wire two ports together
remove_line(alias)	Remove a connection line
create_supercomponent(...)	Group components into a reusable sub-circuit
change_submodel(alias, submodel_name, submodel_path)	Assign a submodel
get_parameter_value(data_path) / set_parameter_value(data_path, value)	Read/write a parameter or state's initial value
get_parameter_infos(data_path)	Type, title, unit of a parameter
generate_code()	Compile the active circuit
set_run_parameter(name, value)	Set a run/simulation parameter
run_simulation()	Run a temporal simulation
get_variable_values(data_path)	Time-series [time, value] pairs from the last run
get_variable_infos(data_path)	Metadata about a variable

connect() checks out one Amesim license token for the whole session — call disconnect() when done so it doesn't block your own interactive Amesim usage.

Troubleshooting

• "AMEPython.exe not found for version ..." — VERSION_DIRS in amesim_api.py doesn't match where Amesim is actually installed on your machine.
• Worker seems to hang or crash silently — check amesim_worker.log in the project root; the worker's stdout/stderr (including any Amesim-side traceback) lands there.
• Stuck holding a license token — call disconnect(), or kill the AMEPython.exe process directly if the MCP server itself is gone.

License

MIT for amesim_mcp/ — see LICENSE. vendor/ bundles third-party packages under their own licenses — see NOTICE.md.

---

amesim-mcp (한국어)

MCP 프로토콜로 Siemens Simcenter Amesim의 Circuit API를 Claude(Desktop/Code)의 도구로 노출하는 서버입니다. 채팅만으로 회로를 만들고, 컴포넌트를 배치·연결하고, 파라미터를 설정하고, 컴파일·시뮬레이션을 실행하고, 결과를 읽어올 수 있습니다.

비공식 개인 프로젝트이며 Siemens와 아무런 제휴·후원 관계가 없습니다. "Simcenter Amesim"은 Siemens의 상표입니다.

동작 원리

Amesim의 Python API는 Amesim에 내장된 Python 3.6 인터프리터인 AMEPython.exe 안에서만 존재합니다. MCP 서버를 AMEPython.exe 위에서 그대로 돌릴 수 없는 이유가 두 가지 있습니다.

1. AMEPython.exe는 시작할 때 Starting Python ... 배너를 표준출력으로 무조건 출력하며 끌 방법이 없습니다. MCP stdio 서버가 이 프로세스로 그대로 동작하면 이 배너가 JSON-RPC 스트림을 깨뜨립니다.
2. AMERunSimulation(및 다른 실행 관련 API로 보이는 함수들)은 메인 스레드가 아닌 다른 스레드에서 호출하면 무한정 멈춥니다. Siemens가 제공하는 scripting/python/serve_api.py 예제는 RPyC 연결을 백그라운드 스레드에서 처리하는 ThreadedServer를 쓰기 때문에 그대로 쓰면 이 문제를 그대로 겪습니다.

그래서 이 프로젝트는 프로세스를 두 개로 나눕니다.

• MCP 서버 (amesim_mcp/server.py) — 일반 Python 3.12+ 프로세스로, Claude와 stdio로 통신합니다.
• 워커(worker) (amesim_mcp/worker_entry.py) — AMEPython.exe 안에서 실행되며, RPyC의 OneShotServer(연결 1개만, 메인 스레드에서 동기적으로 처리 — 이게 바로 위 hang 문제를 피하는 방법입니다)를 띄웁니다. 이 워커의 표준출력/에러(배너 포함)는 amesim_worker.log로 리다이렉트되어 MCP 서버 자신의 stdio에는 절대 섞이지 않습니다.

MCP 서버는 로컬 TCP 포트(기본값 18861)로 이 워커에 일반적인 RPyC 클라이언트처럼 접속합니다.

AMEPython.exe의 내장 인터프리터는 pip도, 인터넷 접근도 안 되기 때문에 워커가 필요로 하는 패키지들(pywin32, rpyc, plumbum, adodbapi)의 빌드된 사본을 vendor/에 함께 담아두었습니다 (각 패키지의 원 라이선스는 NOTICE.md 참고). 워커 프로세스를 띄울 때 vendor/가 PYTHONPATH 맨 앞에 추가됩니다.

요구 사항

• Windows, Simcenter Amesim 설치 (기본 설정은 2021.1과 2404 — 다른 버전/경로를 쓰려면 아래 참고).
• MCP 서버 자체를 돌릴 Python 3.12+ (Amesim에 내장된 3.6과는 별개의, 시스템에 설치된 일반 Python).
• Claude Desktop 또는 Claude Code (다른 MCP 호환 클라이언트도 가능).

설치

git clone <이 저장소 URL>
cd amesim-mcp
py -3.13 -m pip install -e .

(3.12 이상이면 어떤 Python이든 됩니다 — py -3.13은 개발할 때 쓴 버전일 뿐입니다.)

Amesim이 C:\Program Files\Simcenter\<버전>\Amesim이 아닌 다른 경로에 설치되어 있거나, 2021.1 / 2404가 아닌 다른 버전을 쓴다면 amesim_mcp/amesim_api.py의 VERSION_DIRS를 수정하세요.

VERSION_DIRS = {
    "2021.1": r"C:\Program Files\Simcenter\2021.1\Amesim",
    "2404": r"C:\Program Files\Simcenter\2404\Amesim",
}

MCP 클라이언트 설정

Claude Desktop — %APPDATA%\Claude\claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "amesim": {
      "command": "py",
      "args": ["-3.13", "-m", "amesim_mcp.server"]
    }
  }
}

Claude Code 등 프로젝트 단위 MCP 클라이언트 — 예제 파일을 복사해서 경로만 바꿔주세요.

cp .mcp.json.example .mcp.json

{
  "mcpServers": {
    "amesim": {
      "command": "python",
      "args": ["-m", "amesim_mcp.server"],
      "cwd": "C:/path/to/amesim-mcp"
    }
  }
}

.mcp.json은 절대경로가 들어가는 개인 환경 설정 파일이라 .gitignore에 포함되어 있습니다 — 커밋하지 마세요.

사용법

일반적인 사용 흐름:

connect → create_circuit → add_component → change_submodel →
connect_two_ports → set_parameter_value → generate_code →
run_simulation → get_variable_values → save_circuit → disconnect

도구	설명
connect(version)	Amesim 워커 시작/연결 ("2021.1" 또는 "2404")
disconnect()	라이선스 토큰 반납, 워커 종료
status()	연결 상태 + Circuit API 버전 확인
execute_python(code)	워커의 지속되는(persistent) 네임스페이스에서 임의 Python 코드 실행 — ame_apy, amesim이 이미 import되어 있음. 전용 도구가 없는 작업이나, execute_python("help(ame_apy.함수이름)")으로 정확한 시그니처를 확인할 때 사용
create_circuit(name)	새 회로 생성
open_ame_file(path)	기존 .ame 파일 열기
save_circuit()	현재 회로 저장
close_circuit(save)	현재 회로 닫기
add_component(icon_name, alias, x, y)	스케치에 컴포넌트 추가
move_component(alias, x, y)	컴포넌트 이동
rotate_component(alias, quarter_turns)	컴포넌트 회전
flip_component(alias)	컴포넌트 좌우 반전
remove_component(alias)	컴포넌트 삭제
connect_two_ports(alias1, port1, alias2, port2)	두 포트를 선으로 연결
remove_line(alias)	연결선 삭제
create_supercomponent(...)	컴포넌트들을 재사용 가능한 슈퍼컴포넌트로 묶기
change_submodel(alias, submodel_name, submodel_path)	서브모델 지정
get_parameter_value(data_path) / set_parameter_value(data_path, value)	파라미터/초기 상태값 읽기·쓰기
get_parameter_infos(data_path)	파라미터의 타입/제목/단위 조회
generate_code()	현재 회로 컴파일
set_run_parameter(name, value)	실행/시뮬레이션 파라미터 설정
run_simulation()	시간 영역 시뮬레이션 실행
get_variable_values(data_path)	마지막 실행의 [time, value] 시계열 값
get_variable_infos(data_path)	변수 메타데이터 조회

connect()는 세션 동안 Amesim 라이선스 토큰을 하나 점유합니다. 다 쓰면 disconnect()를 호출해서 본인의 대화형 Amesim 사용을 막지 않도록 하세요.

문제 해결

• "AMEPython.exe not found for version ..." — amesim_api.py의 VERSION_DIRS 경로가 실제 설치 경로와 다릅니다.
• 워커가 멈춘 것 같거나 조용히 죽는 경우 — 프로젝트 루트의 amesim_worker.log를 확인하세요. 워커의 표준출력/에러(Amesim 쪽 트레이스백 포함)가 여기 남습니다.
• 라이선스 토큰을 반납하지 못하고 물려있는 경우 — disconnect()를 호출하거나, MCP 서버 자체가 죽었다면 AMEPython.exe 프로세스를 직접 종료하세요.

라이선스

amesim_mcp/는 MIT 라이선스입니다 — LICENSE 참고. vendor/는 각 패키지의 원 라이선스를 그대로 유지합니다 — NOTICE.md 참고.