Materials Project MCP

Consulte o banco de dados do Materials Project usando o cliente mp_api. Requer a variável de ambiente MP_API_KEY.

GitHub

Documentação

Materials Project MCP

Um servidor Model Context Protocol (MCP) para consultar o banco de dados do Materials Project usando o cliente mp_api.

Requisitos

Chave de API do Materials Project - Obtenha uma aqui (conta gratuita necessária)
Docker Desktop (deve estar em execução)
Python 3.12+ com uv

Obtendo Sua Chave de API do Materials Project

Visite Materials Project
Crie uma conta gratuita ou faça login
Vá para o seu painel
Navegue até as configurações de API
Gere ou copie sua chave de API
Mantenha esta chave segura - você precisará dela para a configuração

Opções de Instalação

Passo 1: Docker (Recomendado)

Usando Docker Run

Instale o Docker Desktop:
- Baixe de docker.com
- Instale e certifique-se de que o Docker Desktop está em execução

Baixe a imagem Docker:

docker pull benedict2002/materials-project-mcp

Teste a instalação:

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

Usando Docker Compose (Mais Fácil)

Instale o Docker Desktop e certifique-se de que está em execução

Clone o repositório:

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

Crie um arquivo .env:

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

Teste a configuração:
```
docker-compose up
```
Para execução em segundo plano:
```
docker-compose up -d
```
Pare o serviço:
```
docker-compose down
```

Passo 1: Instalação Local com Python

Instale o uv (se ainda não estiver instalado):

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

Clone o repositório:

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

Crie e ative o ambiente virtual:

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

Instale as dependências:
```
uv pip install -r requirements.txt
```

Defina sua chave de API:

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

Teste a instalação:
```
python server.py
```

Passo 2: Configuração com Claude Desktop

Localize seu arquivo de configuração do Claude:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Escolha seu método de configuração:

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

Substitua your-materials-project-api-key pela sua chave de API real
Certifique-se de que o Docker Desktop está em execução
Reinicie o Claude Desktop
Verifique a instalação:
- Abra um novo chat no Claude
- Pergunte algo como "Pesquise materiais de silício no banco de dados do Materials Project" ou teste qualquer uma das ferramentas disponíveis.
- Você deve ver dados do Materials Project na resposta

Configuração com VS Code Copilot

Abra as Configurações do VS Code:
- Pressione Ctrl+Shift+P (Windows/Linux) ou Cmd+Shift+P (macOS)
- Digite "Preferences: Open User Settings (JSON)"
- Selecione-o para abrir settings.json

Adicione a configuração 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: Configuração local com 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
}

Substitua os placeholders:
- your-api-key pela sua chave de API do Materials Project
- /path/to/your/server.py pelo caminho real para server.py
Certifique-se de que o Docker Desktop está em execução (para configurações Docker)
Reinicie o VS Code
Teste no VS Code:
- Abra o chat/copilot do VS Code
- Pergunte sobre materiais do Materials Project
- O contêiner Docker iniciará automaticamente quando o VS Code fizer solicitações

Testes e Desenvolvimento (desenvolvedores)

Testando Sua Instalação

Teste o servidor MCP localmente:
```
mcp dev server.py
```
Procure a linha "🔗 Open inspector with token pre-filled:" e use essa URL

Fluxo de Trabalho de Desenvolvimento

Crie um branch de funcionalidade:
```
git checkout -b feature-name
```

Faça suas alterações e teste:

# 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

Faça commit e push:

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

Abra um pull request

Ferramentas e Recursos Disponíveis

search_materials - Pesquise por elementos, faixa de band gap, estabilidade
get_structure_by_id - Obtenha estruturas cristalinas e parâmetros de rede
get_electronic_bandstructure - Plote estruturas de bandas eletrônicas
get_electronic_dos_by_id - Obtenha densidade eletrônica de estados
get_phonon_bandstructure - Plote estruturas de bandas de fônons
get_phonon_dos_by_id - Obtenha densidade de estados de fônons
get_ion_reference_data_for_chemsys - Baixe dados de referência de íons aquosos para diagramas de Pourbaix
get_cohesive_energy - Calcule energias coesivas
get_atom_reference_data - Recupere energias de referência de átomos neutros isolados
get_magnetic_data_by_id - Propriedades magnéticas e ordenação
get_charge_density_by_id - Dados de densidade de carga
get_dielectric_data_by_id - Constantes e propriedades dielétricas
get_diffraction_patterns - Difração de raios X e nêutrons
get_xRay_absorption_spectra - Espectros XAFS, XANES, EXAFS
get_elastic_constants - Propriedades mecânicas
get_suggested_substrates - Encontre substratos para filmes finos
get_thermo_stability - Análise de estabilidade termodinâmica
get_surface_properties - Energias de superfície, funções trabalho e formas de Wulff
get_grain_boundaries - Contornos de grão calculados para um material
get_insertion_electrodes - Dados de eletrodos de inserção e baterias
get_oxidation_states - Estados de oxidação de elementos, fórmula e informações de estrutura

Solução de Problemas

Problemas Comuns

Erro "Invalid API key":
- Verifique se sua chave de API está correta
- Verifique se você definiu a variável de ambiente corretamente
- Certifique-se de que sua conta do Materials Project está ativa
"Docker not found" ou "Cannot connect to Docker daemon":
- Certifique-se de que o Docker Desktop está instalado e em execução
- Você deve ver o ícone do Docker Desktop na bandeja do sistema/barra de menus
- Tente docker --version para verificar se o Docker está acessível
- No Windows/Mac: Abra o aplicativo Docker Desktop
- No Linux: Inicie o serviço Docker com sudo systemctl start docker
Problemas de inicialização do contêiner:
- Os contêineres Docker iniciam automaticamente quando o Claude/VS Code faz solicitações
- Não é necessário iniciar contêineres manualmente - eles são efêmeros (iniciar → executar → parar)
- Cada consulta cria uma nova instância de contêiner
Problemas com Docker Compose:
- Certifique-se de que o Docker Compose está instalado: docker-compose --version
- Verifique se o arquivo .env existe e tem a chave de API correta
- Verifique se o arquivo docker-compose.yml está no local correto
- Certifique-se de que o Docker Desktop está em execução
Servidor MCP não reconhecido no Claude:
- Verifique o caminho do seu arquivo de configuração
- Verifique se a sintaxe JSON está correta
- Reinicie o Claude Desktop após alterações de configuração
- Certifique-se de que o Docker Desktop está em execução

Obtendo Ajuda

MCP Inspector: Use mcp dev server.py para testes interativos e depuração.
GitHub Issues: Crie um Issue para relatórios de bugs, solicitações de recursos ou perguntas.
Documentação da API do Materials Project: docs.materialsproject.org
Documentação do MCP: modelcontextprotocol.io
Ajuda do Docker: docs.docker.com

Autores

Benedict Debrah
Peniel Fiawornu

Referência

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