NEMAD MCP

A standalone Model Context Protocol server for the Northeast Materials Database (NEMAD) at nemad.org. Connect an MCP-compatible assistant to read-only material searches without giving the assistant your API key in a prompt.

• Website and account: https://nemad.org

• NEMAD API documentation: https://nemad.org/api-docs

• Source and issues: https://github.com/Yibo-Zhang/nemad-mcp

Requirements

• Python 3.12 or newer

• uv

• A NEMAD account/API key for material queries (startup, discovery, and local cache inspection work without a key)

This project uses the official MCP Python SDK 2.x (tested and locked at 2.3.0), not the unrelated third-party fastmcp package. It supports the 2026-07-28 protocol via server/discover and older clients via the SDK's initialize compatibility path. The automated tests exercise both eras. See the official SDK migration guide.

Related MCP server: MCP Materials Server

Quick start

Get a key from your NEMAD account. Keep it in an environment variable or your MCP client's secret store, never in Git or a chat prompt.

export NEMAD_API_KEY="your-api-key"
uvx --from git+https://github.com/Yibo-Zhang/nemad-mcp nemad-mcp

This starts a stdio server: it waits for an MCP client rather than showing an interactive prompt. Ctrl-C stops it. mcp-nemad is also provided as a backward-compatible executable name. The package has not been published to PyPI; use the Git URL or a local checkout, not uvx nemad-mcp alone.

To pin the source revision, replace the Git URL with git+https://github.com/Yibo-Zhang/nemad-mcp@<reviewed-commit-sha>. This fixes the source, not its transitive dependencies. For a locked dependency environment, use the local checkout instructions with uv sync --locked below.

MCP client configuration

In an MCP client that accepts a command/args configuration:

{
  "mcpServers": {
    "nemad": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Yibo-Zhang/nemad-mcp",
        "nemad-mcp"
      ],
      "env": {
        "NEMAD_API_KEY": "your-api-key"
      }
    }
  }
}

The key above is a placeholder. Prefer your client's secret facility when available. If your GUI client cannot find uvx, use its absolute installed path. Restart or reconnect the client after changing its configuration.

Local checkout

git clone https://github.com/Yibo-Zhang/nemad-mcp.git
cd nemad-mcp
uv sync --locked
uv run --locked nemad-mcp --help
uv run --locked nemad-mcp

A local client can use uv --directory /absolute/path/to/nemad-mcp run --locked nemad-mcp.

Optional local Streamable HTTP

uv run --locked nemad-mcp --transport streamable-http --port 8000

Connect a compatible client to http://127.0.0.1:8000/mcp. This mode is bound to loopback and is single-user only. The process shares one API key and one cache; it is not a multi-tenant hosted service and does not implement user authentication. Do not publicly proxy it. Legacy SSE is not exposed by this CLI; use stdio for older clients or Streamable HTTP for current clients.

Tools

All tools return schema-described structured results with a text fallback. Expected failures are MCP tool errors (isError: true), not successful text containing an error message.

database_type is one of magnetic, magnetic_anisotropy, thermoelectric, or superconductor. Availability and permissions are controlled by the NEMAD API.

Example tool arguments:

{"database_type":"magnetic","elements":"Fe,Co","exact_match":false,"limit":100}

count is the number of matches NEMAD returned, capped by limit; it is not the database total. To find out whether more exist, search again with a higher limit.

Use the returned cache_key in nemad_read_results. start_index is inclusive and end_index is exclusive. A page contains at most 100 records; omitting end_index requests the next 100. Empty search results produce an empty page.

Search limit defaults to 100. It accepts 1–1000, or -1 for all results subject to a 10 MiB response-size bound. Prefer a finite limit. Up to 32 searches are cached for 15 minutes. Cache keys are opaque, process-local, and lost on restart. These bounds, opaque keys, and structured output replace the earlier implementation's unbounded cache and text-only result format.

Configuration and safety

The base URL must include the API prefix /api. An override is available for trusted alternative deployments and local tests. Only HTTPS or loopback HTTP is accepted. Do not send a production key to an untrusted override.

Requests have a 30-second timeout. Redirects are not followed, and HTTP response bodies, credentials, and raw exception details are not copied into tool errors. The server uses GET requests only. Query results are untrusted source data, not instructions for the assistant.

Development and verification

uv sync --locked
uv run --locked ruff check .
uv run --locked ruff format --check .
uv run --locked pytest -q
uv build

Tests cover API requests against mocks, input/error handling, bounded caching, structured tool output, in-process discovery, and actual stdio subprocesses using both the current protocol and the legacy handshake. No production API key is required by tests or CI. Passing these checks does not establish authenticated production query availability; that must be verified separately with the account owner's key. This repository does not deploy NEMAD or publish a PyPI package.

License

MIT. See LICENSE for the license and applicable copyright notices.