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

Visit Materials 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

Installation Options

Step 1: Docker (Recommended)

Using Docker Run

Install Docker Desktop:
- Download from docker.com
- Install and make sure Docker Desktop is running

Pull the Docker image:

docker pull benedict2002/materials-project-mcp

Test the installation:

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

Using Docker Compose (Easiest)

Install Docker Desktop and make sure it's running

Clone the repository:

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

Create a .env file:

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

Test the setup:
```
docker-compose up
```
For background running:
```
docker-compose up -d
```
Stop the service:
```
docker-compose down
```

Step 1 : Local Python Installation

Install uv (if not already installed):

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

Clone the repository:

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

Create and activate virtual environment:

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

Install dependencies:
```
uv pip install -r requirements.txt
```

Set your API key:

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

Test the installation:
```
python server.py
```

Step 2 : Setup with Claude Desktop

Locate your Claude configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

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"
      ]
    }
  }
}

Replace your-materials-project-api-key with your actual API key
Ensure Docker Desktop is running
Restart Claude Desktop
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

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

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
}

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
}

Replace placeholders:
- your-api-key with your Materials Project API key
- /path/to/your/server.py with the actual path to server.py
Ensure Docker Desktop is running (for Docker configurations)
Restart VS Code
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

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

Development Workflow

Create a feature branch:
```
git checkout -b feature-name
```

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

Commit and push:

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

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

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

Materials Project Platform MCP Server

README Documentation