What databases can I query with the OPTIMADE MCP Server?

You can query OPTIMADE-compatible materials science databases such as Materials Project, Materials Cloud, and COD. The server can discover additional public OPTIMADE endpoints via the `list_providers()` tool.

How do I install the OPTIMADE MCP Server?

Install it using `uv pip install optimade-mcp-server`. You can then configure it in your MCP client (like Cline) by adding it to your configuration with the command `uvx optimade-mcp-server`.

What happens if I try to query a field that isn't whitelisted?

The `lint_filter` tool will return a warning (not block the query) for non-whitelisted fields. The model should surface this warning and get your confirmation before executing the query.

Where are query results stored and how do I access them later?

Query results are saved locally as full JSON and can be retrieved later using the `optimade://results/ ` resource, where the UUID is provided in the query response.

What should I do if I'm behind a VPN or proxy?

Add `HTTP_PROXY` and/or `HTTPS_PROXY` environment variables to a `.env` file in your project root.

MCP Connector

Query Materials Science Databases via Natural Language

Name: Optimade MCP Server
Availability: OnlineOnly
Author: dianfengxiaobo

Query OPTIMADE-compatible materials databases (Materials Project, Materials Cloud, COD) with LLM-generated filters and lint checks.

Connect

dianfengxiaobo

Own this? Claim it

Maintainer of this project? Claim this page to edit the listing.

Spark score

out of 100

Updated 11 months ago

Fresher alternatives ↓

Version 1.0.0

Models

universal

Add to Favorites

Why it matters

Access and query diverse materials science databases (Materials Project, Materials Cloud, COD) using natural language. This asset translates natural language into OPTIMADE filters, executes queries, and stores results locally.

Outcomes

What it gets done

Query multiple OPTIMADE-compatible databases.

Translate natural language into OPTIMADE query filters.

Validate filter syntax and check against whitelisted properties.

Store query results locally with automatic summaries.

Install

Add it to your toolbox

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/vb-optimade-mcp | bash

Capabilities

Tools your agent gets

lint_filter

Validates the syntax of OPTIMADE filters and checks against a whitelist of requested properties

query_optimade

Executes queries to OPTIMADE databases with result preview and full JSON storage

list_providers

Discovers available global public OPTIMADE endpoints

Overview

Optimade MCP Server

OPTIMADE MCP Server lets an AI assistant query OPTIMADE-compatible materials databases by generating and linting query filters, executing them against provider endpoints, and saving full results as JSON resources. Use it when querying materials science databases via natural language. Non-whitelisted filter fields return a warning that should be surfaced and confirmed before querying, not silently allowed.

What it does

OPTIMADE MCP Server lets an AI assistant query OPTIMADE-compatible materials science databases - such as Materials Project, Materials Cloud, and COD - through natural language, with the LLM generating the OPTIMADE query filter itself. It performs structured data queries across multiple OPTIMADE databases via the MCP protocol, with filter presets and provider endpoints fully configurable. Query results are saved locally as full JSON, with a summary generated during the interaction; the full result can always be retrieved afterward via its optimade://results/<uuid> resource.

When to use - and when NOT to

Use it when you want to search materials databases using OPTIMADE's filter grammar without hand-writing the query syntax - the LLM composes the filter, the server validates it against a whitelist of queryable properties, and executes it against one or more provider endpoints. Every query needs two things: the OPTIMADE filter and which database(s) to query. Do not assume all fields are safe to query freely - lint_filter distinguishes whitelisted "MUST be queryable" fields from others; non-whitelisted fields return a warning (not blocked) and the model should surface that warning and get confirmation before querying.

Capabilities

Tools:

lint_filter(filter): validate a filter, returning "ok", "warn: ..." (field not whitelisted but allowed), or "syntax error: ..." (blocked).
query_optimade(filter, baseUrls?): execute a query, returning a preview (first 5 results) plus a link to the full JSON resource.
list_providers(): discover global public OPTIMADE endpoints.

Resources (must be explicitly read via resources/read, not auto-injected):

optimade://docs/filters - filter grammar and examples.
optimade://spec/queryable_props - whitelist of queryable fields.
optimade://docs/providers - default provider URLs.
optimade://docs/filter_presets - named filter snippets.
optimade://prompts/ask_for_provider - system prompt guiding URL selection and linting.
optimade://results/<uuid> - full JSON of a past query.

Provider resolution falls back in order: user-provided baseUrls, then config defaults, then a single fallback mirror (https://optimade.fly.dev) - this fallback is applied automatically whenever baseUrls are omitted, without requiring extra configuration.

How to install

uv pip install optimade-mcp-server

The server is easily deployable via uvx and is compatible with clients such as Cline. Configure your MCP client (e.g. cline):

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

For VPN/proxy use, add HTTP_PROXY/HTTPS_PROXY to a .env file in the project root.

Who it's for

Materials scientists and researchers who want an AI assistant to query OPTIMADE-federated materials databases in natural language instead of hand-writing OPTIMADE filter syntax. The project is MIT-licensed.

Source README

OPTIMADE MCP SERVER

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

FAQ

Common questions

Discussion

Query Materials Science Databases via Natural Language

What it gets done

Add it to your toolbox

Tools your agent gets

Optimade MCP Server

What it does

When to use - and when NOT to

Capabilities

How to install

Who it's for

OPTIMADE MCP SERVER

🎯 Overview

✨ Features

🧩 What the LLM can read (Resources)

⚙️ Installation & Usage

✅ Recommended via uv

🌐 Proxy Support (Optional)

🪪 License

🙋 FAQ

Common questions

Questions & comments · 0