This release is a pre-release and may not be stable for production use.
⚛️ MCP Atomic Toolkit
[!NOTE] This project is under active development. Interfaces and behavior may evolve.
A FastMCP server for atomistic modeling workflows powered by ASE, pymatgen, and modern ML interatomic potentials.
It gives MCP clients a practical toolkit for:
- building structures,
- running geometry optimization + molecular dynamics,
- analyzing structures/trajectories,
- and downloading generated artifacts (data + plots).
✨ Why this repo
If you need atomistic workflows exposed as MCP tools (instead of hand-wiring scripts), this project gives you:
- ready-to-call MCP tools for common simulation tasks,
- file-first outputs that are easy to inspect/reuse,
- artifact download URLs so clients don’t need binary blobs in chat context,
- deployment-ready HTTP app with health and server-card endpoints.
🚀 Features
- MCP-native workflows via FastMCP tools
- Structure generation: bulk, surface, molecule, supercell, amorphous, liquid, bicrystal, polycrystal
- Optimization workflows with MLIPs (
nequixdefault,orbsupported) - Molecular dynamics workflows (Velocity Verlet, Langevin, NVT Berendsen)
- Analysis outputs:
- RDF + coordination stats
- MSD + thermodynamic trends
- VACF + diffusion (Green-Kubo)
- Downloadable artifacts (
xyz,extxyz,cif,traj,png,svg,csv,dat, ...) - Registry-friendly endpoints (
/healthz, server card, Streamable HTTP root)
⚡ Quick Start
1) Requirements
- Python 3.11+
2) Install
pip install -r requirements.txt
3) Run locally
uvicorn mcp_atomictoolkit.http_app:app --host 0.0.0.0 --port 10000
Alternative:
python main.py
4) Smoke check
curl -s http://localhost:10000/healthz
Expected response:
{"status":"ok"}
🧰 Tooling Overview
Main MCP tools exposed by the server:
build_structure_workflowanalyze_structure_workflowwrite_structure_workflowoptimize_structure_workflowrun_md_workflowanalyze_trajectory_workflowautocorrelation_workflow
Legacy aliases are also included for backward compatibility.
🌐 Endpoints
POST /— primary MCP Streamable HTTP endpointGET /healthz— health checkGET /.well-known/mcp/server-card.json— MCP server card metadataGET /artifacts/{artifact_id}/{filename}— artifact download route/sse/— compatibility alias path mounted to the MCP app
📦 Deployment
Render
render.yaml is included and ready to use.
Default start command:
uvicorn mcp_atomictoolkit.http_app:app --host 0.0.0.0 --port $PORT
Docker
docker build -t mcp-atomictoolkit .
docker run --rm -p 7860:7860 mcp-atomictoolkit
🗂️ Project Structure
src/mcp_atomictoolkit/
mcp_server.py # FastMCP tool definitions
http_app.py # Starlette app + routing/endpoints
workflows/core.py # High-level workflow orchestration
analysis/ # Structure/trajectory/VACF analysis logic
structure_operations.py
optimizers.py
md_runner.py
artifact_store.py # Download artifact registration + URLs
📈 GitHub Pulse
Add your repository path in the URLs below to enable live charts.
Star history
🤝 Contributing
- Keep outputs file-based and artifact-friendly.
- When adding tools, usually update both:
workflows/core.pymcp_server.py
- Preserve
http_app.pycompatibility behavior unless intentionally changing deployment contracts.
📄 License
MIT — see LICENSE.
Metadata
Release files for iflow-mcp_xirtamesrevni-mcp-atomictoolkit 0.1.0.dev0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_xirtamesrevni_mcp_atomictoolkit-0.1.0.dev0.tar.gz | 27.1 kB | Without provenance | Details for iflow_mcp_xirtamesrevni_mcp_atomictoolkit-0.1.0.dev0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_xirtamesrevni_mcp_atomictoolkit-0.1.0.dev0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_xirtamesrevni_mcp_atomictoolkit-0.1.0.dev0-py3-none-any.whl |
Total release size: 58.9 kB
Release files / iflow_mcp_xirtamesrevni_mcp_atomictoolkit-0.1.0.dev0.tar.gz
| Download URL | iflow_mcp_xirtamesrevni_mcp_atomictoolkit-0.1.0.dev0.tar.gz |
|---|---|
| Size | 27.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0e33ab94b9741035e523977123d80f68676e838f28aa99d195eb3c6f60663003
|
|
BLAKE2b-256 checksum How to use checksums |
8a4094319943fad06ead9977afddc96cda1f84598fe906a7a69dc9d8bb5f5e40
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_xirtamesrevni_mcp_atomictoolkit-0.1.0.dev0-py3-none-any.whl
| Download URL | iflow_mcp_xirtamesrevni_mcp_atomictoolkit-0.1.0.dev0-py3-none-any.whl |
|---|---|
| Size | 31.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
16033d3aa5e37504988dbe7a3675e401d794755056d40d8bc9126c60c9397f1b
|
|
BLAKE2b-256 checksum How to use checksums |
1050efccc900a5bbeade466a5ae01f7b082e0c31832571b27573ddbc0a588b97
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_xirtamesrevni-mcp-atomictoolkit 0.1.0.dev0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.