<div align="center">

SciMCP

An MCP Server for Computational Materials Science

Connect AI coding assistants to practical workflows for molecular dynamics, crystallography, rheology, and materials analysis.

Compatible with: Claude Desktop · Claude Code · Cursor · Windsurf · Any MCP-compatible client

---

uvx scimcp

Run SciMCP instantly without installing it globally.

</div>

---

Overview

SciMCP is a Model Context Protocol server designed for computational materials science.

It allows MCP-compatible AI assistants to generate LAMMPS simulations, parse simulation outputs, analyze particle alignment, detect plastic rearrangements, and study shear rheology through a collection of 12 specialized tools.

Instead of manually preparing scripts and transferring simulation results between different programs, you can describe the task directly to your AI assistant.

For example:

Generate a three-stage LAMMPS workflow for a Lennard-Jones system under shear.

Parse this LAMMPS trajectory and summarize the temperature evolution.

Calculate the nematic order parameter from these quaternion data.

Generate simulations for shear rates between 0.0001 and 0.05.

---

Key Features

• Generate complete LAMMPS input scripts
• Create multi-stage minimization, equilibration, and production workflows
• Parse LAMMPS thermo logs and trajectory files
• Calculate nematic order parameters and alignment profiles
• Compute the Falk–Langer (D^2_{\min}) non-affine displacement metric
• Identify particles involved in plastic rearrangements
• Generate shear-rate sweeps automatically
• Estimate viscosity using a power-law rheological model
• Work directly from MCP-compatible AI clients
• Run with uvx without a permanent installation

---

Quick Start

1. Run or install SciMCP

The recommended method is to run SciMCP directly with uvx:

uvx scimcp

Alternatively, install it with pip:

pip install scimcp

Or add it to a project using uv:

uv add scimcp

---

2. Connect SciMCP to an MCP client

<details> <summary><b>Claude Desktop</b></summary>

Add the following configuration to:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "scimcp": {
      "command": "uvx",
      "args": ["scimcp"]
    }
  }
}

Restart Claude Desktop after saving the configuration.

</details>

<details> <summary><b>Claude Code</b></summary>

Run:

claude mcp add scimcp -- uvx scimcp

</details>

<details> <summary><b>Cursor or Windsurf</b></summary>

Add SciMCP to your MCP configuration:

{
  "mcpServers": {
    "scimcp": {
      "command": "uvx",
      "args": ["scimcp"]
    }
  }
}

</details>

---

3. Start using the tools

After connecting SciMCP, ask your AI assistant to perform a materials-science task.

Examples:

Generate a LAMMPS input file for 1,000 Lennard-Jones atoms in the NVT ensemble at 300 K with applied shear.

Parse this lammpstrj file and report the box dimensions, atom positions, and velocity statistics.

Compute the nematic order parameter and the corresponding Q-tensor from these quaternion data.

Generate a shear-rate sweep at 0.0001, 0.001, 0.01, and 0.05.

---

Available Tools

SciMCP currently provides 12 tools organized into five categories.

1. LAMMPS Input Generation

Tool	Description
lammps_generate_input	Generates complete LAMMPS input scripts. Supports Lennard-Jones, EAM, Tersoff, Buckingham, and Coulomb potentials; NVT, NPT, NVE, and NPH ensembles; and optional shear deformation.
lammps_generate_workflow	Creates a multi-stage workflow consisting of minimization, equilibration, and production phases. The ensemble, temperature, simulation length, and shear conditions can be configured for each phase.

---

2. Output Parsing

Tool	Description
lammps_parse_thermo	Parses LAMMPS thermo logs into structured data and calculates minimum, maximum, mean, and standard deviation values for each column.
lammps_parse_dump	Parses lammpstrj trajectory files and extracts atom positions, velocities, simulation-box dimensions, and frame information.
lammps_file_summary	Automatically detects whether a file contains thermo or trajectory data and returns its most important metrics.

---

3. Nematic Alignment Analysis

Tool	Description
lammps_nematic_order	Calculates the scalar nematic order parameter (S) and the complete Q-tensor from quaternion data. Values near (S=1) indicate strong alignment, while values near (S=0) indicate isotropic orientation.
lammps_nematic_vs_z	Calculates the spatial nematic-order profile (S(z)) along the z-axis.
lammps_nematic_vs_time	Calculates the time evolution of the nematic order parameter (S(t)) over a trajectory.

---

4. Non-Affine Displacement and Plasticity

Tool	Description
lammps_d2min	Calculates the Falk–Langer (D^2_{\min}) metric, which measures the deviation of local particle motion from an affine deformation.
lammps_identify_plastic_events	Detects particles involved in plastic rearrangements using a configurable (D^2_{\min}) threshold.

---

5. Shear Rheology

Tool	Description
lammps_shear_sweep	Generates LAMMPS input files for multiple shear rates and produces a corresponding JSON configuration file.
lammps_estimate_viscosity	Fits stress-versus-shear-rate data to a power-law model and returns the consistency index (K), flow index (n), and rheological classification.

---

Python Example

The SciMCP modules can also be used directly from Python.

from scimcp.tools.lammps.generator import generate_workflow
from scimcp.tools.lammps.shear import SweepConfig, write_sweep_scripts

# Generate a three-phase LAMMPS workflow with shear
script = generate_workflow(
    atoms_per_side=12,
    potential="lj",
    temperature=300,
    n_production_steps=100_000,
    apply_shear=True,
    shear_rate=0.001,
)

print(script)

# Generate input files for a shear-rate sweep
config = SweepConfig(
    shear_rates=[0.0001, 0.001, 0.01, 0.05],
    atoms_per_side=10,
    temperature=300,
)

files = write_sweep_scripts(config)

for file in files:
    print(file)

This sweep generates files such as:

in.shear_0p000100
in.shear_0p001000
in.shear_0p010000
in.shear_0p050000

---

Example Analysis Output

Nematic Order Analysis
----------------------
Aligned particles:        S = 1.0000
Random particles:         S = 0.3880
Partially aligned system: S = 0.4049

Nematic Profile S(z)
--------------------
z_center       S      count
    0.50    1.0000      10
    5.50    0.4483      10
    9.50    0.5590      10

Viscosity Estimation
--------------------
Power-law flow index: n = 0.80
Classification: Shear-thinning

Shear rate     Viscosity
0.0001         3.15
0.0100         1.26
0.0500         0.91

For the power-law model,

[ \tau = K\dot{\gamma}^{,n}, ]

where:

• (\tau) is the shear stress
• (K) is the consistency index
• (\dot{\gamma}) is the shear rate
• (n) is the flow index

The material is classified as:

• Shear-thinning when (n<1)
• Newtonian when (n\approx1)
• Shear-thickening when (n>1)

---

Supported Interatomic Potentials

Potential	LAMMPS style	Typical applications
Lennard-Jones	lj/cut	Noble gases, generic liquids, and model particle systems
EAM	eam/alloy	Metallic systems such as Cu, Al, Ni, and Fe
Tersoff	tersoff	Covalent materials and semiconductors such as Si, C, and Ge
Buckingham	buck/coul/long	Ionic materials and oxide systems
Coulomb	coul/long	Long-range electrostatic interactions in charged systems

---

Project Structure

scimcp/
├── src/
│   └── scimcp/
│       ├── server.py
│       └── tools/
│           └── lammps/
│               ├── generator.py
│               ├── parser.py
│               ├── nematic.py
│               ├── nonaffine.py
│               ├── shear.py
│               └── templates/
├── tests/
├── examples/
├── pyproject.toml
└── README.md

Main modules

Module	Purpose
server.py	MCP server entry point containing the registered tools and prompts
generator.py	LAMMPS input generation and multi-stage workflow construction
parser.py	Thermodynamic-log and trajectory-file parsing
nematic.py	Q-tensor, (S(t)), and (S(z)) calculations
nonaffine.py	Falk–Langer (D^2_{\min}) calculations and plastic-event detection
shear.py	Shear-rate sweep generation and viscosity-model fitting
templates/	Reference LAMMPS input templates

---

Testing

SciMCP includes 51 unit tests covering input generation, output parsing, nematic analysis, non-affine displacement, and shear rheology.

Run the complete test suite:

pytest

Run the tests with detailed output:

pytest -v

Run a specific test module:

pytest tests/test_nematic.py -v

---

Contributing

Contributions are welcome, including:

• Bug fixes
• New scientific-analysis tools
• Additional LAMMPS potentials and ensembles
• Performance improvements
• Documentation updates
• Tests and examples

To set up a local development environment:

git clone https://github.com/Nour-elhaq/scimcp.git
cd scimcp
pip install -e ".[dev]"
pytest

Please open an issue before making major architectural changes or introducing a large new feature.

---

Roadmap

Planned features include:

• [ ] CIF and DFT output parsing
• [ ] Crystal-structure analysis
• [ ] Materials Project API integration
• [ ] MXene database queries
• [ ] Machine-learning-based property prediction
• [ ] Atomic Simulation Environment integration
• [ ] Interactive trajectory visualization
• [ ] Additional molecular-dynamics analysis tools

---

License

SciMCP is distributed under the MIT License.

---

Citation

When SciMCP contributes to published research, consider citing the repository or its associated publication.

A formal citation file can be provided through a future CITATION.cff release.

---

<div align="center">

Built for the computational materials science community

Report a Bug · Request a Feature

</div>