serpent2-mcp
This server is an MCP interface for Serpent2 that lets AI agents access documentation, validate inputs, run calculations, and inspect results.
Environment info: detect Serpent binary, version, data libraries, and config status
Documentation: exact card syntax, semantic/full-text search, card listing, bundled examples, doc cache sync
Validation: static linting of inputs (cards, references, material mixing, source consistency) plus optional
sss2 -noruncheckRun calculations: launch Serpent jobs in background with OMP/MPI options, force/validate control, isolated workdirs
Job management: check status, tail logs, kill running jobs
Results: parse
_res.mand detector/depletion files, extract variables, plot keff/detector/burnup curvesData libraries: list official VTT libraries and download/extract them to local storage
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@serpent2-mcp validate my input file and run the serpent calculation"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Установка
Нужен установленный uv и своя лицензионная копия Serpent — бинарник и библиотека сечений в репозиторий не входят.
git clone https://github.com/ShuwiOwO/Serpent2-mcp && cd Serpent2-mcp
cp /путь/к/sss2 bin/sss2 && chmod +x bin/sss2 # свой бинарник
cp -R /путь/к/xsdata/* libraries/ # своя библиотека сечений
./setup.sh # установка и настройкаsetup.sh проверит окружение, перепривяжет пути внутри библиотеки, поставит
Python-окружение и прогонит эталонный расчёт.
В Claude Code сервер нужно
один раз одобрить (при запуске в папке или вручную через команду/mcp); OpenCode подхватывает сервер автоматически.
Related MCP server: OpenKer Modeler MCP Server
Инструменты
Инструмент | Что делает |
| точный синтаксис карты или |
| семантический поиск по документации |
| проверка на наличие нуклида в локальной библиотеке |
| статическая проверка входа без запуска: карты, типы поверхностей, связки |
| запуск расчета в папке |
| чтение и разбор |
| выводит версию Serpent2, число нуклидов в библиотеках, состояние индексов |
| список известных карт и |
Устройство
serpent2-mcp/
├── bin/ ← ваш бинарник (sss2)
├── libraries/ ← ваша библиотека сечений
├── projects/ ← рабочие проекты
├── runs/ ← изолированные папки для запусков расчетов
├── examples/ ← эталонные задачи для проверки работоспособности
├── tools/ ← сервер, линтер, парсеры, RAG
├── datasets/ ← индекс карт + документация в markdown
├── rag_store/ ← готовый векторный индекс
├── .mcp.json ← для Claude Code
└── opencode.json ← для OpenCodeДокументация собрана в двух версиях: wiki 2.1.x для старой версии, docs 2.2.5 — современный мануал. docs_card по
умолчанию отдаёт документацию для 2.1.x.
Проверка и возможные ошибки
.venv/bin/python tools/serpent_mcp_server_test.py # Ручной запуск MCP
.venv/bin/python tools/serpent_lint_test.py # Проверка работы линтера
.venv/bin/python tools/serpent_results_test.py # Проверка работы парсера выходных файлов
.venv/bin/python tools/rag_eval.py --top 5 # Проверка работоспособности RAGЕсли что-то не так:
Симптом | Причина | Решение |
| нет |
|
| пусто в |
|
| пути в индексе старые |
|
| не поставлен |
|
сервер не подключается | нет |
|
Available Tools
16 toolsdownload_data_libraryA
Start a background download of a Serpent data library into a local directory (resumable, extracts tar.gz; multi-GB transfers report progress via job_status). The download runs on THIS machine (the one hosting the MCP server). Use name from list_data_libraries, or an explicit url.
Inputs: url, dest, name, extract, +2 more. Returns: result
get_cardA
Get the exact syntax, parameter list, notes and documentation link for a Serpent input card or set option. Examples: 'surf', 'mat', 'src', 'set acelib', 'acelib', 'sb'.
Inputs: name (required). Returns: result
get_environmentA
Show detected Serpent executable, version, CLI flag style, data libraries, server configuration and documentation cache status. Call this first on a new machine or when a run fails with 'sss2 not found'.
Inputs: refresh. Returns: result
get_examplesA
List bundled Serpent input examples (pin cell, shielding, burnup, group constants, minimal sphere). With topic, return the best matching example content.
Inputs: topic. Returns: result
get_referenceA
Return the curated Serpent 2 quick reference (modes, geometry, materials, sources, detectors, burnup, group constants, CLI options, output files, pitfalls). Optionally request one topic (e.g. 'geometry', 'burnup', 'source', 'versions').
Inputs: topic. Returns: result
get_resultsB
Read and summarise Serpent output files. Defaults to the newest _res.m in the workdir; returns k-eff estimates, run parameters, integral rates and optionally detector/depletion summaries. Use variables=[...] to extract specific _res.m variables.
Inputs: file, input, workdir, max_rows, +2 more. Returns: result
job_killA
Terminate a running background job (SIGTERM, then SIGKILL for local jobs).
Inputs: job_id (required). Returns: result
job_outputB
Read more log output from a background job (tail of the run log).
Inputs: job_id (required), tail_chars. Returns: result
job_statusA
Check background job state (running/finished/failed/lost), exit code, progress and recent log output. Without job_id, list the most recent jobs.
Inputs: tail, job_id. Returns: result
list_cardsA
List all known Serpent input cards and set options, optionally filtered by kind (card|set|all). Useful for discovery when the exact name is unknown.
Inputs: kind. Returns: result
list_data_librariesA
List the official VTT Serpent nuclear data libraries that can be downloaded (ENDF/B-VII.1, JEFF-3.2, JENDL-4.0, FENDL-3.0, decay/fission-yield/photon data). Each entry has key, title, size, URL and file name.
Inputs: no named parameters. Returns: result
plot_resultsA
Draw a PNG plot from Serpent output. kind: detector (needs name), keff (k-eff per step), burnup (BU vs DAYS from _dep.m), variables (needs x and y variable names). Returns the path of the written image.
Inputs: kind (required), x, y, file, +5 more. Returns: result
runB
Start a Serpent calculation as a background job and return its job id (long runs must not block). By default the input is statically validated first; pass force=true to skip. options: extra CLI flags, e.g. ['--noplot']. omp/mpi_tasks are convenience shortcuts.
Inputs: input (required), omp, force, backend, +4 more. Returns: result
search_docsA
Full-text search across the indexed official Serpent documentation (syntax manual, user guide, appendices, wiki). kind: all|card|guide|extra|wiki. Returns matching sections with source links.
Inputs: query (required), kind, limit. Returns: result
sync_docsB
Trigger or refresh the download/index of the official Serpent documentation cache (runs in the background). Returns current sync status.
Inputs: force. Returns: result
validate_inputA
Statically validate a Serpent input file (and its includes): known cards/options, duplicate names, undefined surface/material/cell/universe references, material unit mixing, source/neutron-mode consistency and more. level=3 (or run_norun=true) also runs sss2 -noplot -norun when the executable is available and parses its exact input errors.
Inputs: text, input, level, run_norun. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
The documentation cluster (get_reference, search_docs, get_card, list_cards, get_examples) has some conceptual proximity, but descriptions clearly differentiate curated reference vs full-text search vs single-card lookup vs discovery vs examples. The job family (job_kill, job_status, job_output) is cleanly separated by purpose, and run/get_results/plot_results target distinct lifecycle stages.
Most tools follow a consistent verb_noun pattern (get_environment, search_docs, validate_input, list_cards, get_results, plot_results, download_data_library). The job_* family is internally consistent but uses noun_verb ordering, and 'run' is a bare verb, which are minor deviations from the dominant convention.
16 tools is reasonable for a complex simulation domain spanning environment detection, documentation, validation, execution, job management, results, plotting and data libraries. Each tool earns its place, though the count sits at the upper edge of comfortable scope.
The surface covers a full workflow: environment setup, doc lookup, input validation, running, job lifecycle, results extraction, plotting and data library management. A minor gap is the absence of a tool to author/write input files or clean up/delete old jobs, but agents can work around these.
Related MCP Connectors
Protocol-native energy infrastructure orchestration for AI data centers. Provides 46 MCP tools across 8 grid protocols (IEC-61850, DNP3, Modbus, OCPP, OpenADR, IEEE 2030.5, IEC 60870-5-104, ICCP) with 5 core API primitives: connect, dispatch, settle, comply, and intel. Enables AI agents to programmatically interact with substations, grid interfaces, and energy assets for real-time workload-grid coordination.
AI Agent Utility Layer for agent safety, web monitoring, crypto research and tool discovery.
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to interact with OrcaSlicer to manage profiles, adjust printing settings, and perform slicing operations. It allows users to search settings, slice STL/3MF files, and analyze G-code metadata through natural language assistants.7AGPL 3.0
- -licenseNot gradedqualityNot gradedmaintenanceEnables AI agents to traverse SysML v2 model graphs, query requirements, and perform impact analysis for model-based systems engineering. It allows agents to interact with plain-text models to automate documentation and refine system architectures.-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to automate COMSOL Multiphysics simulations, including model management, geometry building, physics configuration, meshing, solving, and results visualization via the MCP protocol.MIT
- AlicenseAqualityAmaintenanceEnables AI to view the Serpentine3D viewport, create NURBS geometry, and execute commands, integrating AI directly into the modelling workflow.15149MIT