Materials Project Platform MCP Server

Materials Project MCP

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

Requirements

• Materials Project API Key - Get one here (free account required)
• Docker Desktop (must be running)
• Python 3.12+ with uv

Getting Your Materials Project API Key

1. Visit Materials Project
2. Create a free account or log in
3. Go to your dashboard
4. Navigate to API settings
5. Generate or copy your API key
6. Keep this key secure - you'll need it for setup

Installation Options

Step 1: Docker (Recommended)

Using Docker Run

1. Install Docker Desktop:
   • Download from docker.com
   • Install and make sure Docker Desktop is running
2. Pull the Docker image:
   docker pull benedict2002/materials-project-mcp
3. Test the installation:
   docker run --rm -i -e MP_API_KEY="your-api-key" benedict2002/materials-project-mcp

Using Docker Compose (Easiest)

1. Install Docker Desktop and make sure it's running
2. Clone the repository:
   git clone <repository-url> cd materials-project-mcp
3. Create a .env file:
   echo "MP_API_KEY=your-materials-project-api-key" > .env
4. Test the setup:
   docker-compose up
5. For background running:
   docker-compose up -d
6. Stop the service:
   docker-compose down

Step 1 : Local Python Installation

1. Install uv (if not already installed):
   curl -Ls https://astral.sh/uv/install.sh | sh
2. Clone the repository:
   git clone <repository-url> cd materials-project-mcp
3. Create and activate virtual environment:
   uv venv source .venv/bin/activate # Linux/macOS # or .venv\Scripts\activate # Windows
4. Install dependencies:
   uv pip install -r requirements.txt
5. Set your API key:
   export MP_API_KEY="your-api-key" # Linux/macOS # or set MP_API_KEY=your-api-key # Windows
6. Test the installation:
   python server.py

Step 2 : Setup with Claude Desktop

1. Locate your Claude configuration file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Choose your configuration method:Using Docker Run
   { "mcpServers": { "Materials Project MCP": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "MP_API_KEY=your-materials-project-api-key", "benedict2002/materials-project-mcp" ] } } }
3. Replace your-materials-project-api-key with your actual API key
4. Ensure Docker Desktop is running
5. Restart Claude Desktop
6. Verify installation:
   • 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

Setup with VS Code Copilot

1. Open VS Code Settings:
   • Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS)
   • Type "Preferences: Open User Settings (JSON)"
   • Select it to open settings.json
2. Add MCP configuration:
   { "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 }
3. 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 }
4. Replace placeholders:
   • your-api-key with your Materials Project API key
   • /path/to/your/server.py with the actual path to server.py
5. Ensure Docker Desktop is running (for Docker configurations)
6. Restart VS Code
7. Test in VS Code:
   • Open VS Code chat/copilot
   • Ask about materials from the Materials Project
   • The Docker container will start automatically when VS Code makes requests

Testing & Development (developers)

Testing Your Installation

1. Test MCP server locally:
   mcp dev server.py
   Look for the line "🔗 Open inspector with token pre-filled:" and use that URL

Development Workflow

1. Create a feature branch:
   git checkout -b feature-name
2. Make your changes and test:
   # 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
3. Commit and push:
   git add . git commit -m "Add feature description" git push origin feature-name
4. Open a pull request

Available Tools & Features

• 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

Troubleshooting

Common Issues

1. "Invalid API key" error:
   • Verify your API key is correct
   • Check that you've set the environment variable properly
   • Ensure your Materials Project account is active
2. "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
   • Try docker --version to verify Docker is accessible
   • On Windows/Mac: Open Docker Desktop application
   • On Linux: Start Docker service with sudo systemctl start docker
3. Container startup issues:
   • 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
4. Docker Compose issues:
   • Make sure Docker Compose is installed: docker-compose --version
   • Check your .env file exists and has the correct API key
   • Verify the docker-compose.yml file is in the correct location
   • Ensure Docker Desktop is running
5. MCP server not recognized in Claude:
   • Check your configuration file path
   • Verify JSON syntax is correct
   • Restart Claude Desktop after configuration changes
   • Ensure Docker Desktop is running

Getting Help

• MCP Inspector: Use mcp dev server.py for interactive testing and debugging.
• GitHub Issues: Create an Issue for bug reports, feature requests, or questions.
• Materials Project API Docs: docs.materialsproject.org
• MCP Documentation: modelcontextprotocol.io
• Docker Help: docs.docker.com

Authors

• Benedict Debrah
• Peniel Fiawornu

Reference

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