Overview

This MCP (Model Context Protocol) server bridges large language models and real-time materials data by exposing an MCP-compatible HTTP interface backed by an Optimade-compliant materials database. It translates LLM context requests into Optimade queries (composition, crystal structure, properties) and returns structured context blocks that LLMs can use to ground reasoning, retrieval-augmented generation, or downstream tooling.

By running this server you get a lightweight, developer-friendly service to fetch up-to-date materials information (elemental composition, lattice parameters, prototypes, calculated properties) in a format suitable for model consumption. This is useful for building ML agents, interactive notebooks, or tooling that needs deterministic, machine-readable materials context.

Features

Proxy to any Optimade-compliant database for real-time query results
Returns MCP-compatible context payloads for LLMs and agents
Query by chemical formula, element set, space group, or property filters
Supports pagination and basic caching for repeated queries
Simple authentication and rate-limiting hooks (configurable)
Docker and local development modes
OpenAPI/Swagger for interactive exploration (if enabled)

Installation / Configuration

Prerequisites: Python 3.8+, Docker (optional)

Clone the repo and install dependencies (virtualenv recommended)

git clone https://github.com/dianfengxiaobo/optimade-mcp-server.git
cd optimade-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Minimal environment variables (example)

Create a .env file or export variables in your shell. Typical options:

OPTIMADE_BASE_URL=https://materials.example.org/optimade/v1
MCP_HOST=0.0.0.0
MCP_PORT=8080
API_KEY=changeme
CACHE_TTL=300          # seconds
ENABLE_SWAGGER=true

Run locally

# with virtualenv active
export $(cat .env | xargs)
python -m optimade_mcp_server.main

Run with Docker

docker build -t optimade-mcp-server .
docker run --env-file .env -p 8080:8080 optimade-mcp-server

Configuration file (YAML) example:

optimade:
  base_url: "https://materials.example.org/optimade/v1"
server:
  host: "0.0.0.0"
  port: 8080
security:
  api_key: "changeme"
cache:
  enabled: true
  ttl_seconds: 300

Available Tools / Resources

OpenAPI/Swagger UI — interactive API docs at /docs or /swagger (if enabled in config)
Example queries — JSON request/response examples in the repo’s examples/ directory
Postman collection — importable collection for testing endpoints
Unit tests — tests/ folder with automated test cases
Readme and CONTRIBUTING — basic developer guidance, issue templates, and how to extend adapters

If the repo is hosted on GitHub (link: https://github.com/dianfengxiaobo/optimade-mcp-server), check the repository for up-to-date docs and the example requests.

API Examples

Request MCP context for a chemical formula via curl:

curl -X POST "http://localhost:8080/mcp/context" \
  -H "Authorization: Bearer changeme" \
  -H "Content-Type: application/json" \
  -d '{
    "query_type": "formula",
    "query": "Fe2O3",
    "fields": ["formula", "structure", "band_gap", "spacegroup"],
    "limit": 5
  }'

Example simplified response (MCP payload):

{
  "mcp_version": "1.0",
  "context_items": [
    {
      "id": "mp-12345",
      "source": "optimade",
      "metadata": {
        "formula": "Fe2O3",
        "spacegroup": "R-3c",
        "band_gap": 2.1
      },
      "content": "<crystallographic information or concise text summary>"
    }
  ],
  "pagination": { "limit": 5, "returned": 1 }
}

Python client example using requests:

import requests
resp = requests.post(
    "http://localhost:8080/mcp/context",
    headers={"Authorization": "Bearer changeme"},
    json={"query_type": "elements", "query": ["Fe","O"], "limit": 3}
)
print(resp.json())

Use Cases

LLM-augmented materials discovery: provide a language model with factual context (composition, crystal prototypes, computed properties) to generate hypotheses or suggest candidate materials.
Automated literature/ELN enrichment: resolve formulas and structures stored in an electronic lab notebook to canonical identifiers and attach structured MCP context.
Interactive research notebooks: fetch up-to-date Optimade entries for visualization or analysis inside Jupyter, then feed the same structured data into an LLM for interpretation.
QA pipelines for computed databases: query entries by property thresholds (e.g., formation energy < X) and create concise MCP summaries for reviewers or downstream agents.

Tips for Developers

Point OPTIMADE_BASE_URL to any Optimade-compliant service (Materials Project, NOMAD, local instances) to reuse existing datasets.
Use caching for expensive structural queries (e.g., CIF downloads) and tune CACHE_TTL to balance freshness vs latency.
Extend the server by adding custom transformers that convert Optimade responses into richer, domain-specific MCP blocks (e.g., include structure images, CIF snippets, or computed-property provenance).

For more details and the latest updates visit the project repository: https://github.com/dianfengxiaobo/optimade-mcp-server.

Optimade MCP Server for Real-Time Materials Queries