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](https://materialsproject.org/) (free account required) - **Docker Desktop** (must be running) - **Python 3.12+** with [uv](https://github.com/astral-sh/uv) ### Getting Your Materials Project API Key 1. Visit [Materials Project](https://materialsproject.org/) 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](https://www.docker.com/products/docker-desktop/) - Install and **make sure Docker Desktop is running** 2. **Pull the Docker image:** ```bash docker pull benedict2002/materials-project-mcp ``` 3. **Test the installation:** ```bash 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:** ```bash git clone <repository-url> cd materials-project-mcp ``` 3. **Create a `.env` file:** ```bash echo "MP_API_KEY=your-materials-project-api-key" > .env ``` 4. **Test the setup:** ```bash docker-compose up ``` 5. **For background running:** ```bash docker-compose up -d ``` 6. **Stop the service:** ```bash docker-compose down ``` ### Step 1 : Local Python Installation 1. **Install uv (if not already installed):** ```bash curl -Ls https://astral.sh/uv/install.sh | sh ``` 2. **Clone the repository:** ```bash git clone <repository-url> cd materials-project-mcp ``` 3. **Create and activate virtual environment:** ```bash uv venv source .venv/bin/activate # Linux/macOS # or .venv\Scripts\activate # Windows ``` 4. **Install dependencies:** ```bash uv pip install -r requirements.txt ``` 5. **Set your API key:** ```bash export MP_API_KEY="your-api-key" # Linux/macOS # or set MP_API_KEY=your-api-key # Windows ``` 6. **Test the installation:** ```bash 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** ```json { "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:** ```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 } ``` 3. **Alternative: Local Python setup for VS Code:** ```json { "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:** ```bash 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:** ```bash git checkout -b feature-name ``` 2. **Make your changes and test:** ```bash # 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:** ```bash 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](https://github.com/yourusername/materials-project-mcp/issues) for bug reports, feature requests, or questions. - **Materials Project API Docs**: [docs.materialsproject.org](https://docs.materialsproject.org/) - **MCP Documentation**: [modelcontextprotocol.io](https://modelcontextprotocol.io/) - **Docker Help**: [docs.docker.com](https://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.