MatRouter

English | 简体中文

MatRouter is a local-first MCP server for agentic materials research. It gives AI agents structured access to materials databases through normalized tools, provenance-aware responses, and lightweight analysis utilities.

Status

v0.2.0 is an offline-tested local release focused on provenance-preserving materials retrieval, evidence workflows, and resilient upstream integrations.

Quick Start

MatRouter requires Python 3.11 or newer.

Install the published package:

uv tool install matrouter

Or install from a source checkout:

git clone https://github.com/MatRouter/matrouter.git
cd matrouter
uv sync

Optional bootstrap check before wiring an agent host:

matrouter --explain-sources

Agent hosts should run MatRouter as a local MCP stdio server:

matrouter

When running from a source checkout instead of the installed tool, prefix the same commands with uv run, for example uv run matrouter --explain-sources.

For Codex and Claude Code, prefer the installable plugin path in docs/usage.md. For OpenCode or other hosts, configure MCP with command: "matrouter" or command: ["matrouter"] and install the portable skill if the host supports skills.

Most starter workflows can use public sources without MatRouter-specific credentials. Materials Project, MaterialsGalaxy detail routes, and MPDS require API keys. Keep real keys in a private env file such as ~/.config/matrouter/env, or in process environment variables; do not commit them to the repository or shared MCP client configuration.

Documentation

• User setup, data-source configuration, MCP client examples, prompts, FAQ, and troubleshooting: docs/usage.md
• Development guide, architecture notes, configuration contract, testing, and release workflow: docs/development.md
• Validation report: docs/test-report.md

Agent Skill

The public MatRouter skill source lives in skills/matrouter/. It is for agents that have, or are being configured to have, MatRouter MCP access. It provides materials-research guidance: source selection, provenance handling, screening, comparison, report packages, conservative evidence interpretation, and MCP initialization when availability is blocked.

For Codex auto-discovery, install it by copying skills/matrouter/ to .agents/skills/matrouter/ in a repo or to $HOME/.agents/skills/matrouter/ for personal use.

For human-facing MCP client setup, use the user guide. After setup, a useful prompt is:

Use MatRouter to find the band structure of diamond and generate a plot.

Contact

Authors:

• Quansheng Wu quansheng.wu@iphy.ac.cn
• Tiannian Zhu (朱天念) tnzhu@iphy.ac.cn

Maintainer:

• Quansheng Wu wuquansheng@gmail.com

License

MatRouter source code is licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.

MatRouter does not grant rights to third-party database content. Data retrieved through MatRouter remains subject to the terms, licenses, API policies, attribution requirements, and access restrictions of the respective upstream data providers.