Optimade MCP Server

What is Optimade MCP Server about?

Optimade MCP Server provides a Model Context Protocol interface for querying OPTIMADE‑compatible material databases (e.g., Materials Project, Materials Cloud, COD). It lets an LLM or user construct OPTIMADE filter strings, selects provider endpoints, executes the query, stores the full JSON response, and generates a concise summary.

How to use Optimade MCP Server?

Installation – Install via the Python UV tool:
```
uv pip install optimade-mcp-server
```

MCP launcher configuration – Register the server in your MCP‑compatible client (e.g., cline) with a stdio entry:

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

Running a query – The client sends two parameters: the OPTIMADE filter string and, optionally, a list of provider base URLs. If no URLs are supplied, the server falls back to configuration defaults and finally to https://optimade.fly.dev.
Accessing results – Full query results are saved under a dynamic URI optimade://results/<uuid> and can be fetched later.

Key Features

MCP Resources: on‑demand URIs for filter grammar, queryable property whitelist, provider list, filter presets, and system prompts.
Tooling: lint_filter validates syntax and whitelist compliance; query_optimade returns a preview of the first five records plus a link to the full JSON; list_providers discovers public OPTIMADE endpoints.
Provider fallback hierarchy – user‑provided → config defaults → single mirror.
Proxy support via .env (HTTP_PROXY, HTTPS_PROXY).
Result persistence – each query stored under optimade://results/<uuid> for later retrieval.
Natural‑language interaction – LLM can generate filter strings from plain English queries.

Use Cases

Researchers needing quick, programmatic access to material properties across multiple databases without writing raw REST calls.
LLM‑driven assistants that translate user questions (e.g., “show me materials with band_gap > 2 eV”) into valid OPTIMADE filters.
Data pipelines that require cached JSON results for downstream analysis while keeping a lightweight summary for reporting.
Educational tools that demonstrate OPTIMADE query syntax and whitelist constraints.

FAQ

Q: Are resources auto‑injected into the model’s context? A: No. The client must explicitly call resources/read or configure a startup step.

Q: Can non‑whitelisted fields be used? A: Yes. lint_filter will return a warning (e.g., warn: band_gap). The model should present the warning and ask for confirmation before querying.

Q: How is the full result accessed? A: The server stores the complete JSON under optimade://results/<uuid>. Retrieve it with a standard resources/read call.

Q: What if I don’t specify a provider URL? A: The server automatically falls back to the configured defaults and ultimately to the mirror https://optimade.fly.dev.

Q: Do I need a proxy? A: Only if your environment requires one. Define HTTP_PROXY and HTTPS_PROXY in a .env file at the project root.

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>.

Optimade MCP Server