Optimade

A Model Context Protocol (MCP) tool for querying Optimade-compatible material databases, fully configurable custom filter presets and provider endpoints.

---

🎯 Overview

This tool enables structured data queries across multiple OPTIMADE databases (e.g., Materials Project, Materials Cloud, COD), via MCP protocol. Key capabilities include:

1..Easily deployable via uvx, cline

2.It is possible to interact with the client in natural language, enabling the large language model to generate the OPTIMADE query filter.

3.The JSON returned by OPTIMADE will be saved locally, and a summary will be generated during the interaction.

Note: The query requires two parameters. One is the optimade query filter, and the other is the database to be queried.

---

✨ Features

• MCP Resources the model can read on demand:
  • optimade://docs/filters – Filter grammar & examples (Markdown)
  • optimade://spec/queryable_props – Whitelist of fields marked “Query: MUST be a queryable property …” (JSON)
  • optimade://docs/providers – Default provider URLs (JSON, generated from config)
  • optimade://docs/filter_presets – Named filter snippets (JSON)
  • optimade://prompts/ask_for_provider – System prompt to guide URL selection & linting (Text)
  • optimade://results/<uuid> – Dynamic: full JSON of past queries
• Tools
  • lint_filter(filter) → "ok" / "warn: …" / "syntax error: …"
    (Warn = not in whitelist but allowed; Syntax error = blocked)
  • query_optimade(filter, baseUrls?) → preview (first 5) + link to full JSON resource
  • list_providers() → Discover global public OPTIMADE endpoints
• Provider fallback
  1. user-provided baseUrls → 2) config defaults → 3) fallback single mirror (https://optimade.fly.dev)
• Proxy-ready via .env (HTTP_PROXY, HTTPS_PROXY).

---

🧩 What the LLM can read (Resources)

URI	Type	Purpose
optimade://docs/filters	text/markdown	Full grammar & examples
optimade://spec/queryable_props	application/json	Whitelist: fields marked “MUST be queryable”
optimade://docs/providers	application/json	Default provider URLs from config
optimade://docs/filter_presets	application/json	Named filter snippets for inspiration
optimade://prompts/ask_for_provider	text/plain	System prompt to guide URL choice & linting
optimade://results/<uuid>	application/json	Dynamic: full JSON from previous queries

Important: Resources are not auto-injected. Your MCP client must call resources/read (or you configure startup/workflow to read them).

---

⚙️ Installation & Usage

✅ Recommended via uv

1.Install the tool:

uv pip install optimade-mcp-server

2.In cline or any MCP-compatible launcher, configure the tool as follows:

{
  "mcpServers": {
    "optimade_mcp_server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "optimade-mcp-server"
      ]
    }
  }
}

---

🌐 Proxy Support (Optional)

If you need to use a VPN or proxy, create a .env file in the project root:

HTTP_PROXY=http://127.0.0.1:<your-port>
HTTPS_PROXY=http://127.0.0.1:<your-port>

If you don't need a proxy, you can comment out or remove the proxy setup in the source code.

---

🪪 License

This project is licensed under the MIT License. See LICENSE for details.

---

🙋 FAQ

Q: Are resources auto‑injected into the model’s context?
A: No. The client must call resources/read (or configure a startup/workflow step). The server does apply provider fallback automatically if baseUrls are omitted.

Q: Can I use non‑whitelisted fields?
A: Yes. lint_filter returns warn: band_gap. The model should show a warning and ask you to confirm before querying.

Q: How do I export the full result?
A: The server always saves a full JSON under optimade://results/<uuid>.