📦 OPTIMADE_MCP_SERVER

A Model Context Protocol (MCP) compliant tool for querying materials structure data from OPTIMADE-compatible databases.

This tool integrates a Python-based OPTIMADE query service with an MCP-compatible TypeScript server. It supports flexible filtering of materials structure data across multiple OPTIMADE providers.

🚀 Features

Query OPTIMADE databases via MCP interface

Filter structures using advanced filter syntax

Customizable provider URLs and presets via config

Supports large-scale result download and retries

How 🧠 Works

Server. It is the main entry point for MCP tools. It:

Read the configuration from config/config.json

Generate a Python child process (optimade_tool.py)

Send JSON queries to the sub-process and return structured results through MCP

optimade_tool.py uses optimade-client to obtain data from the remote database and save the results to the disk or display them in the interactive interface.

Installation

   npm install

   npm run build

   python -m venv .venv

   .venv\Scripts\activate

   pip install -r requirements.txt

Configure

Currently, this project only recommends local running servers

{
  "mcpServers": {
    "optimade": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "node",
      "args": [
        "/path/to/your/project/dist/server.js"
      ]
    }
  }
}

📍 please send/path/to/your/project/dist/server js replacement for your local server or the deployment environment. Js the absolute path or a relative path.

Requirements

It is recommended to use nodejs version v20.19.0

🌐 Proxy setup (VPN/HTTP_PROXY configuration)

In the Python query script optimade_tool.py, the local proxy configuration is enabled by default:

os.environ["HTTP_PROXY"] = "http://127.0.0.1:<your_proxy_port>"
os.environ["HTTPS_PROXY"] = "http://127.0.0.1:<your_proxy_port>"

✅ If you can access an external OPTIMADE data source without a VPN: Please comment out or delete the above two lines.

✅ If you use a VPN or proxy tools (such as Clash) : Please replace <your_proxy_port> with the local port number of your proxy software.