Materials Project MCP

Consulta la base de datos de Materials Project usando el cliente mp_api. Requiere la variable de entorno MP_API_KEY.

Documentación

Materials Project MCP

Un servidor de Protocolo de Contexto de Modelos (MCP) para consultar la base de datos de Materials Project utilizando el cliente mp_api.

Requisitos

Clave de API de Materials Project - Obtén una aquí (se requiere cuenta gratuita)
Docker Desktop (debe estar en ejecución)
Python 3.12+ con uv

Cómo Obtener tu Clave de API de Materials Project

Visita Materials Project
Crea una cuenta gratuita o inicia sesión
Ve a tu panel de control
Navega a la configuración de API
Genera o copia tu clave de API
Mantén esta clave segura: la necesitarás para la configuración

Opciones de Instalación

Paso 1: Docker (Recomendado)

Usando Docker Run

Instala Docker Desktop:
- Descárgalo desde docker.com
- Instálalo y asegúrate de que Docker Desktop esté en ejecución

Descarga la imagen de Docker:

docker pull benedict2002/materials-project-mcp

Prueba la instalación:

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

Usando Docker Compose (Más Fácil)

Instala Docker Desktop y asegúrate de que esté en ejecución

Clona el repositorio:

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

Crea un archivo .env:

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

Prueba la configuración:
```
docker-compose up
```
Para ejecución en segundo plano:
```
docker-compose up -d
```
Detén el servicio:
```
docker-compose down
```

Paso 1: Instalación Local con Python

Instala uv (si aún no está instalado):

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

Clona el repositorio:

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

Crea y activa el entorno virtual:

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

Instala las dependencias:
```
uv pip install -r requirements.txt
```

Configura tu clave de API:

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

Prueba la instalación:
```
python server.py
```

Paso 2: Configuración con Claude Desktop

Localiza tu archivo de configuración de Claude:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Elige tu método de configuración:

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

Reemplaza your-materials-project-api-key con tu clave de API real
Asegúrate de que Docker Desktop esté en ejecución
Reinicia Claude Desktop
Verifica la instalación:
- Abre un nuevo chat en Claude
- Pregunta algo como "Busca materiales de silicio en la base de datos de Materials Project" o prueba cualquiera de las herramientas disponibles.
- Deberías ver datos de Materials Project en la respuesta

Configuración con VS Code Copilot

Abre la Configuración de VS Code:
- Presiona Ctrl+Shift+P (Windows/Linux) o Cmd+Shift+P (macOS)
- Escribe "Preferences: Open User Settings (JSON)"
- Selecciónalo para abrir settings.json

Agrega la configuración de MCP:

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

Alternativa: Configuración local de Python para 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
}

Reemplaza los marcadores de posición:
- your-api-key con tu clave de API de Materials Project
- /path/to/your/server.py con la ruta real a server.py
Asegúrate de que Docker Desktop esté en ejecución (para configuraciones de Docker)
Reinicia VS Code
Prueba en VS Code:
- Abre el chat/copilot de VS Code
- Pregunta sobre materiales de Materials Project
- El contenedor de Docker se iniciará automáticamente cuando VS Code realice solicitudes

Pruebas y Desarrollo (desarrolladores)

Probando tu Instalación

Prueba el servidor MCP localmente:
```
mcp dev server.py
```
Busca la línea "🔗 Open inspector with token pre-filled:" y usa esa URL

Flujo de Trabajo de Desarrollo

Crea una rama de características:
```
git checkout -b feature-name
```

Haz tus cambios y prueba:

# 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

Haz commit y push:

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

Abre una solicitud de extracción (pull request)

Herramientas y Funciones Disponibles

search_materials - Busca por elementos, rango de banda prohibida, estabilidad
get_structure_by_id - Obtén estructuras cristalinas y parámetros de red
get_electronic_bandstructure - Grafica estructuras de bandas electrónicas
get_electronic_dos_by_id - Obtén densidad de estados electrónicos
get_phonon_bandstructure - Grafica estructuras de bandas fonónicas
get_phonon_dos_by_id - Obtén densidad de estados fonónicos
get_ion_reference_data_for_chemsys - Descarga datos de referencia de iones acuosos para diagramas de Pourbaix
get_cohesive_energy - Calcula energías cohesivas
get_atom_reference_data - Recupera energías de referencia de átomos neutros aislados
get_magnetic_data_by_id - Propiedades magnéticas y ordenamiento
get_charge_density_by_id - Datos de densidad de carga
get_dielectric_data_by_id - Constantes y propiedades dieléctricas
get_diffraction_patterns - Difracción de rayos X y neutrones
get_xRay_absorption_spectra - Espectros XAFS, XANES, EXAFS
get_elastic_constants - Propiedades mecánicas
get_suggested_substrates - Encuentra sustratos para películas delgadas
get_thermo_stability - Análisis de estabilidad termodinámica
get_surface_properties - Energías superficiales, funciones de trabajo y formas de Wulff
get_grain_boundaries - Límites de grano calculados para un material
get_insertion_electrodes - Datos de electrodos de inserción y baterías
get_oxidation_states - Estados de oxidación de elementos, fórmula e información estructural

Solución de Problemas

Problemas Comunes

Error de "Clave de API inválida":
- Verifica que tu clave de API sea correcta
- Comprueba que hayas configurado la variable de entorno correctamente
- Asegúrate de que tu cuenta de Materials Project esté activa
"Docker no encontrado" o "No se puede conectar al daemon de Docker":
- Asegúrate de que Docker Desktop esté instalado y en ejecución
- Deberías ver el ícono de Docker Desktop en la bandeja del sistema/barra de menú
- Prueba docker --version para verificar que Docker sea accesible
- En Windows/Mac: Abre la aplicación Docker Desktop
- En Linux: Inicia el servicio de Docker con sudo systemctl start docker
Problemas de inicio del contenedor:
- Los contenedores de Docker se inician automáticamente cuando Claude/VS Code realiza solicitudes
- No es necesario iniciar contenedores manualmente: son efímeros (inicio → ejecución → detención)
- Cada consulta crea una instancia de contenedor nueva
Problemas con Docker Compose:
- Asegúrate de que Docker Compose esté instalado: docker-compose --version
- Verifica que tu archivo .env exista y tenga la clave de API correcta
- Verifica que el archivo docker-compose.yml esté en la ubicación correcta
- Asegúrate de que Docker Desktop esté en ejecución
Servidor MCP no reconocido en Claude:
- Verifica la ruta de tu archivo de configuración
- Verifica que la sintaxis JSON sea correcta
- Reinicia Claude Desktop después de los cambios de configuración
- Asegúrate de que Docker Desktop esté en ejecución

Obteniendo Ayuda

Inspector MCP: Usa mcp dev server.py para pruebas interactivas y depuración.
Problemas de GitHub: Crea un problema para informes de errores, solicitudes de funciones o preguntas.
Documentación de la API de Materials Project: docs.materialsproject.org
Documentación de MCP: modelcontextprotocol.io
Ayuda de Docker: docs.docker.com

Autores

Benedict Debrah
Peniel Fiawornu

Referencia

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