abacus

The ABACUS MCP Server provides automated computational workflows for quantum chemistry and materials science using the ABACUS package. It exposes a range of calculation types (SCF, geometry optimization, MD, band structure, density of states, and charge density analysis) along with intelligent assistant features (parameter suggestions, input validation, failure diagnosis, and cost estimation) and PyABACUS integration for Python-based workflows. Users interact with the server through an MCP client by describing their calculation needs in natural language or structured requests, and the server automatically configures parameters, builds inputs, and runs ABACUS-based tasks. Typical use cases include performing SCF calculations on a crystal, optimizing structures, analyzing electronic properties like band gaps, and leveraging PyABACUS modules for advanced analysis.

To use it, point your MCP client configuration to the abacus-mcp-server, ensuring Python is the execution environment. You provide a structured description of the desired computation (for example, specifying material, structure type, basis and pseudopotentials, and target properties), and the server returns results, recommendations, and potential optimizations. Common capabilities include: running SCF with validated input, conducting geometry and lattice optimizations, performing MD simulations and trajectory analysis, computing band structures and DOS, and using the PyABACUS interface for extended analyses such as orbital overlaps and workflow guidance. The server also includes troubleshooting aids to diagnose convergence issues and estimate resource needs.

Examples of typical interactions include requesting a silicon crystal SCF calculation with a specified energy cutoff and k-point grid, initiating a perovskite geometry optimization with electronic property calculations, or performing a graphene band-structure path along Γ–M–K–Γ, with the server providing parameters and execution plans.

Prerequisites:

• Python 3.8+ (and virtual environment support)
• ABACUS installed and accessible from the command line
• Access to the MCP client that will consume the server API

Step 1: Clone the MCP server repository

git clone https://github.com/your-org/abacus-mcp-server.git
cd abacus-mcp-server

Step 2: Create and activate a virtual environment (recommended)

python -m venv venv
source venv/bin/activate  # on Unix/macOS
venv\Scripts\activate     # on Windows

Step 3: Install Python dependencies

pip install -r requirements.txt

Step 4: Ensure ABACUS is installed and in PATH

• Install ABACUS following the official ABACUS documentation.
• Verify ABACUS is accessible:

abacus --version

Step 5: Run the MCP server

python src/server.py

Step 6: Configure your MCP client to connect to the server as described in the mcp_config section.

Optional: If you maintain environment variables, you can set them in a dotenv file or your shell, for example:

export PYTHONPATH=/path/to/abacus-mcp-server
export ABACUS_CMD=abacus

Tips and common considerations:

• Ensure ABACUS is available in PATH when the server runs, otherwise specify the full path in configuration.
• Use the provided input validation and parameter suggestion features to reduce convergence issues and optimize resource usage.
• For large calculations, consider setting up a dedicated work directory and organizing pseudos in a consistent directory (as referenced by the config and examples).
• If you encounter convergence problems, enable verbose/debug logging (export LOG_LEVEL=DEBUG) and consult the diagnostic tools exposed by the MCP server.
• The server integrates PyABACUS modules for advanced workflow guidance; leverage PyABACUS in Python-based automation pipelines for enhanced analytics.
• If running in containers or on clusters, map the pseudos and work directories into the container and ensure ABACUS dependencies are installed there.