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.