Goldilocks MCP

Provide a k-point generation tool under the SSSP1.3 PBEsol pseudopotential for Quantum ESPRESSO, including k-point spacing prediction and grid generation functions, supporting different confidence levels and model choices.

Research and data Developer tools #Quantum computing #Material simulation #K-point generation #Pseudopotential tool .Python

rating : 2.5 points

downloads : 6.6K

update time : 2026-03-13

Open Site

What is the Goldilocks MCP Server?

The Goldilocks MCP Server is an intelligent parameter recommendation tool specifically designed for Quantum ESPRESSO, a popular first-principles calculation software. It uses machine learning models (ALIGNN and Random Forest) to predict the optimal settings of the k-point grid in material calculations, ensuring a balance between calculation accuracy and efficiency.

How to use the Goldilocks MCP Server?

Through clients that support the MCP protocol, such as Claude Desktop, you can request k-point parameters just like having a conversation with an assistant. Simply provide the path to the material structure file, select the confidence level and model type, and the server will return the recommended k-point spacing or a complete k-point grid.

Applicable scenarios

It is suitable for researchers who use Quantum ESPRESSO for material electronic structure calculations, especially those who want to automate parameter settings, avoid manual trial and error, and ensure the reliability of calculations.

Main features

Intelligent k-point spacing prediction

Based on the crystal structure of the material, predict the optimal k-point spacing (k-spacing) required for Quantum ESPRESSO calculations, balancing calculation accuracy and efficiency.

Automatic k-point grid generation

Automatically generate a complete k-point grid (kmesh) based on the predicted k-point spacing, which can be directly used in the Quantum ESPRESSO input file.

Confidence level control

Provide three confidence levels (0.85, 0.9, 0.95) to allow users to choose different reliability levels according to their calculation needs.

Dual model support

Support two machine learning models, ALIGNN (an advanced model based on graph neural networks) and Random Forest (RF), to meet different needs.

SSSP pseudopotential optimization

Specifically optimized for the SSSP1.3 PBEsol efficiency version pseudopotential library to ensure that the prediction results are consistent with the best practices of this pseudopotential library.

Advantages

Save computational resources: Avoid overly dense k-point grids and reduce unnecessary calculation time.

Improve reliability: Provide verified parameter recommendations based on a large amount of training data.

User-friendly: Interact through natural language without the need to memorize complex commands.

Flexible configuration: Multiple confidence levels and model choices to meet different calculation needs.

Special optimization: Deeply optimized for Quantum ESPRESSO and the SSSP pseudopotential library.

Limitations

Only support the SSSP1.3 PBEsol efficiency version pseudopotential. Other pseudopotentials may require adjustment.

Require the path to the structure file and cannot directly process structure data.

Installation requires additional dependencies (PyTorch Geometric), which may increase the deployment complexity.

Currently mainly targeted at conventional materials. Manual verification may be required in extreme cases.

How to use

Installation preparation

Ensure that Python 3.11 and the uv package manager are installed on the system, and clone the Goldilocks repository.

Create a virtual environment

Create a Python virtual environment using uv and activate it.

Install dependencies

Install basic dependencies and PyTorch Geometric (which needs to be installed separately).

Configure Claude Desktop

Edit the Claude Desktop configuration file and add the Goldilocks MCP Server.

Start using

Start Claude Desktop and interact with the Goldilocks Server through natural language.

Usage examples

Preliminary screening of new materials

When researching new materials, it is necessary to quickly determine appropriate calculation parameters to avoid non - convergence or unreliable results due to improper k-point settings.

Optimization of calculation parameters

Based on existing calculation results, it is hoped to optimize calculation parameters to reduce calculation time while maintaining sufficient accuracy.

Batch material calculation

High - throughput calculations need to be performed on multiple materials, and an automated parameter setting process is required.

Frequently Asked Questions

What structure file formats does Goldilocks support?

How to choose the confidence level?

What is the difference between the ALIGNN and Random Forest models?

What should I do if I encounter problems when installing PyTorch Geometric?

Can it be used for non - SSSP pseudopotentials?

How to verify the accuracy of the prediction results?

Related resources

Goldilocks GitHub repository

Source code, issue tracking, and latest updates

Quantum ESPRESSO official website

Official documentation of the first - principles calculation software

SSSP pseudopotential library

Standard solid - state pseudopotential library, including the PBEsol efficiency version

MCP protocol documentation

Official documentation and specifications of the Model Context Protocol

PyTorch Geometric installation guide

Detailed guide to solve installation problems of PyTorch Geometric

Claude Desktop configuration

How to configure Claude Desktop to use the MCP Server

🚀 Goldilocks MCP server

This project offers k-point generation tools for Quantum ESPRESSO, utilizing the SSSP1.3 PBEsol efficiency version of pseudo-potentials.

✨ Features

estimate_kpoint_distance

It requires specifying the path to the structure file, the confidence level (the models are trained for levels 0.85, 0.9, and 0.95), and the model (ALIGNN or RF).

Example prompt: "Can you please generate k-points spacing for structure 'path/to/BaGa4.cif', confidence level 0.95 with ALIGNN model?"

It outputs the predicted k-spacing and the confidence interval.

generate_kpoint_grid

It requires specifying the path to the structure file, the confidence level (the models are trained for levels 0.85, 0.9, and 0.95), and the model (ALIGNN or RF).

Example prompt: "Can you please generate k-points grid for structure 'path/to/BaGa4.cif', confidence level 0.95 with ALIGNN model?"

It outputs the predicted kmesh, generated using the lower bound of the k-spacing interval (to ensure that the probability that the predicted value is in agreement with the confidence level).

📦 Installation

Installing MCP-server locally

Install uv (https://docs.astral.sh/uv/getting-started/installation/)
Clone the repository:

git clone https://github.com/stfc/goldilocks-mcp.git
cd goldilocks-mcp

Create a virtual environment and install dependencies:

uv venv --python 3.11
source .venv/bin/activate
uv pip install -e .

Install pytorch-geometric (it can't be installed from pyproject.toml but is required). See details at https://pytorch-geometric.readthedocs.io/en/latest/install/installation.html

uv pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.8.0+cpu.html
uv pip install torch_geometric

Adding mcp to Claude Desktop

To add goldilocks-mcp to Claude Desktop:

Open or create the Claude Desktop configuration file:
- macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: See instructions at https://modelcontextprotocol.io/docs/develop/build-server
If the file doesn't exist, create it with the content from claude_desktop_config.json. If it already exists, merge the goldilocks-mcp entry into the existing mcpServers object.
Important: Update the path in the config file. Replace "absolute/path/to/goldilocks-mcp/goldilocks_mcp/" with the actual absolute path to the goldilocks_mcp directory in your cloned repository.