Materials Project MCP

A Model Context Protocol (MCP) server for querying the Materials Project database using the mp_api client.

- Materials Project API Key-Get one here(free account required)
- Docker Desktop(must be running)
- Python 3.12+withuv
- VisitMaterials Project
- Create a free account or log in
- Go to your dashboard
- Navigate to API settings
- Generate or copy your API key
- Keep this key secure - you'll need it for setup

- Download fromdocker.com
- Install andmake sure Docker Desktop is running

docker pull benedict2002/materials-project-mcp

docker run --rm -i -e MP_API_KEY="your-api-key" benedict2002/materials-project-mcp

git clone <repository-url> cd materials-project-mcp

echo "MP_API_KEY=your-materials-project-api-key" > .env

curl -Ls https://astral.sh/uv/install.sh | sh

git clone <repository-url> cd materials-project-mcp

uv venv source .venv/bin/activate # Linux/macOS # or .venv\Scripts\activate # Windows

export MP_API_KEY="your-api-key" # Linux/macOS # or set MP_API_KEY=your-api-key # Windows

{ "mcpServers": { "Materials Project MCP": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "MP_API_KEY=your-materials-project-api-key", "benedict2002/materials-project-mcp" ] } } }

Replaceyour-materials-project-api-keywith your actual API key

- Open a new chat in Claude
- Ask something like "Search for silicon materials in the Materials Project database" or test any of the availabe tools.
- You should see Materials Project data in the response

- PressCtrl+Shift+P(Windows/Linux) orCmd+Shift+P(macOS)
- Type "Preferences: Open User Settings (JSON)"
- Select it to open settings.json

{ "mcp": { "inputs": [], "servers": { "Materials Project MCP": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "MP_API_KEY=your-api-key", "benedict2002/materials-project-mcp" ] } } }, "chat.mcp.discovery.enabled": true, "workbench.secondarySideBar.showLabels": false }

Alternative: Local Python setup for VS Code:

{ "mcp": { "inputs": [], "servers": { "Materials Project MCP": { "command": "/usr/local/bin/uv", "args": [ "run", "--with", "mcp[cli],aiohttp,pydantic,mp_api,pymatgen,emmet-core", "/path/to/your/server.py" ], "env": { "MP_API_KEY": "your-api-key" } } } }, "chat.mcp.discovery.enabled": true }

- your-api-keywith your Materials Project API key
- /path/to/your/server.pywith the actual path to server.py

Ensure Docker Desktop is running(for Docker configurations)

- Open VS Code chat/copilot
- Ask about materials from the Materials Project
- The Docker container will start automatically when VS Code makes requests
- Test MCP server locally:

mcp dev server.py

# Local testing with MCP Inspector mcp dev server.py # Use the inspector URL to test your changes interactively # Docker testing docker build -t materials-project-mcp-local . docker run --rm -i -e MP_API_KEY="your-api-key" materials-project-mcp-local # Docker Compose testing docker-compose up --build

git add . git commit -m "Add feature description" git push origin feature-name

- search_materials- Search by elements, band gap range, stability
- get_structure_by_id- Get crystal structures and lattice parameters
- get_electronic_bandstructure- Plot electronic band structures
- get_electronic_dos_by_id- Get electronic density of states
- get_phonon_bandstructure- Plot phonon band structures
- get_phonon_dos_by_id- Get phonon density of states
- get_ion_reference_data_for_chemsys- Download aqueous ion reference data for Pourbaix diagrams
- get_cohesive_energy- Calculate cohesive energies
- get_atom_reference_data- Retrieve reference energies of isolated neutral atoms
- get_magnetic_data_by_id- Magnetic properties and ordering
- get_charge_density_by_id- Charge density data
- get_dielectric_data_by_id- Dielectric constants and properties
- get_diffraction_patterns- X-ray and neutron diffraction
- get_xRay_absorption_spectra- XAFS, XANES, EXAFS spectra
- get_elastic_constants- Mechanical properties
- get_suggested_substrates- Find substrates for thin films
- get_thermo_stability- Thermodynamic stability analysis
- get_surface_properties- Surface energies, work functions, and Wulff shapes
- get_grain_boundaries- Computed grain boundaries for a material
- get_insertion_electrodes- Insertion electrode and battery data
- get_oxidation_states- Element oxidation states, formula, and structure info

- Verify your API key is correct
- Check that you've set the environment variable properly
- Ensure your Materials Project account is active

"Docker not found" or "Cannot connect to Docker daemon":

- Make sure Docker Desktop is installed and running
- You should see the Docker Desktop icon in your system tray/menu bar
- Trydocker --versionto verify Docker is accessible
- On Windows/Mac: Open Docker Desktop application
- On Linux: Start Docker service withsudo systemctl start docker

- Docker containers start automatically when Claude/VS Code makes requests
- No need to manually start containers - they're ephemeral (start → run → stop)
- Each query creates a fresh container instance

- Make sure Docker Compose is installed:docker-compose --version
- Check your.envfile exists and has the correct API key
- Verify the docker-compose.yml file is in the correct location
- Ensure Docker Desktop is running

- Check your configuration file path
- Verify JSON syntax is correct
- Restart Claude Desktop after configuration changes
- Ensure Docker Desktop is running

- MCP Inspector: Usemcp dev server.pyfor interactive testing and debugging.
- GitHub Issues:Create an Issuefor bug reports, feature requests, or questions.
- Materials Project API Docs:docs.materialsproject.org
- MCP Documentation:modelcontextprotocol.io
- Docker Help:docs.docker.com

Yin, Xiangyu. 2025. "Building an MCP Server for the Materials Project." March 23, 2025.https://xiangyu-yin.com/content/post_mp_mcp.html.

Access NCBI's suite of APIs, including E-utilities, BLAST, PubChem, and PMC services.