GLPI MCP Server
by efssantos
README.md
# GLPI MCP Server
Servidor MCP desenvolvido em Python que integra assistentes de IA ao GLPI por meio da API REST legada (`apirest.php`). Com ele, um cliente compatível com o Model Context Protocol (MCP) pode pesquisar registros, consultar itens e gerenciar chamados, respeitando as permissões da conta configurada no GLPI.
## Índice
- [Como funciona](#como-funciona)
- [Pré-requisitos](#pré-requisitos)
- [Preparar o GLPI](#preparar-o-glpi)
- [Configuração](#configuração)
- [Executar localmente com Python](#executar-localmente-com-python)
- [Executar com Docker](#executar-com-docker)
- [Conectar a um cliente MCP](#conectar-a-um-cliente-mcp)
- [Ferramentas disponíveis](#ferramentas-disponíveis)
- [Testes automatizados](#testes-automatizados)
- [Solução de problemas](#solução-de-problemas)
- [Segurança](#segurança)
## Como funciona
O GLPI MCP Server funciona como uma ponte entre o cliente MCP (por exemplo, Claude Desktop) e a API REST do GLPI:
```text
Assistente/cliente MCP <--> GLPI MCP Server <--> API REST do GLPI
```
O servidor oferece dois modos de transporte:
- **stdio**: recomendado quando o cliente MCP inicia o servidor como um processo local.
- **Streamable HTTP**: recomendado para execução como serviço, acessível por um cliente remoto ou por um proxy reverso.
## Pré-requisitos
Para execução local:
- Python 3.11 ou superior.
- Acesso de rede à instância GLPI.
- API REST legada habilitada no GLPI.
- Token de aplicação e credenciais/token de usuário com as permissões necessárias.
Para execução em contêiner:
- Docker Engine e o comando `docker`.
- Docker Compose não é necessário: os exemplos abaixo usam diretamente `docker build` e `docker run`.
> **Compatibilidade:** este projeto utiliza a API REST legada do GLPI (`apirest.php`). Verifique se ela está habilitada e disponível na sua instalação. A API REST v2 de versões recentes pode ter fluxo de autenticação diferente e não é o alvo desta implementação.
## Preparar o GLPI
1. Entre no GLPI com uma conta administradora.
2. Habilite e configure a API REST legada nas configurações de API da sua instalação.
3. Gere um **App-Token** (token da aplicação).
4. Gere um **User Token** para a conta de integração ou prepare um usuário e senha dedicados.
5. Conceda à conta somente as permissões necessárias para as operações que pretende executar.
Os nomes dos menus podem variar conforme a versão e o idioma do GLPI. Consulte a documentação correspondente à sua versão para habilitar a API e gerar os tokens.
Você precisará da URL base do GLPI, por exemplo `https://glpi.suaempresa.com`. Não inclua `/apirest.php` no valor de `GLPI_URL`; o caminho da API é configurado separadamente.
## Configuração
Clone o repositório e entre na pasta:
```bash
git clone https://github.com/efssantos/glpi-mcp.git
cd glpi-mcp
```
Crie um arquivo `.env` na raiz do projeto usando `.env.example` como referência. Exemplo:
```dotenv
GLPI_URL=https://glpi.suaempresa.com
GLPI_API_PATH=/apirest.php
GLPI_APP_TOKEN=COLOQUE_SEU_APP_TOKEN
# Use GLPI_USER_TOKEN ou, alternativamente, GLPI_USERNAME + GLPI_PASSWORD.
GLPI_USER_TOKEN=COLOQUE_SEU_USER_TOKEN
# GLPI_USERNAME=usuario-integracao
# GLPI_PASSWORD=sua-senha
GLPI_TIMEOUT=30
GLPI_VERIFY_TLS=true
# Para cliente local iniciado como processo:
MCP_TRANSPORT=stdio
MCP_HOST=127.0.0.1
MCP_PORT=8000
LOG_LEVEL=INFO
```
Ajuste os valores de acordo com seu ambiente:
| Variável | Obrigatória | Descrição |
|---|---:|---|
| `GLPI_URL` | Sim | URL base da instalação GLPI, sem o caminho da API. |
| `GLPI_API_PATH` | Não | Caminho da API. Padrão: `/apirest.php`. |
| `GLPI_APP_TOKEN` | Conforme GLPI | Token da aplicação, quando exigido pela configuração da API. |
| `GLPI_USER_TOKEN` | Uma forma de autenticação | Token do usuário. Alternativamente, use usuário e senha. |
| `GLPI_USERNAME` | Uma forma de autenticação | Usuário da conta de integração. |
| `GLPI_PASSWORD` | Uma forma de autenticação | Senha da conta de integração. |
| `GLPI_TIMEOUT` | Não | Tempo limite das requisições em segundos. Padrão: `30`. |
| `GLPI_VERIFY_TLS` | Não | Valida o certificado TLS. Padrão: `true`. |
| `MCP_TRANSPORT` | Não | `stdio` ou `streamable-http`. Padrão: `stdio`. |
| `MCP_HOST` | Não | Interface de escuta HTTP. Padrão: `127.0.0.1`. |
| `MCP_PORT` | Não | Porta HTTP. Padrão: `8000`. |
Não compartilhe o arquivo `.env`, tokens ou senhas. O arquivo já deve permanecer fora do Git por meio do `.gitignore`.
## Executar localmente com Python
### Windows (PowerShell)
Crie e ative um ambiente virtual:
```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
```
Se o PowerShell bloquear a ativação do ambiente virtual, consulte as políticas de execução da sua organização ou execute os comandos usando o Python do ambiente virtual diretamente.
Configure as variáveis de ambiente a partir do arquivo `.env` ou defina-as na sessão do PowerShell. Para definir manualmente:
```powershell
$env:GLPI_URL = "https://glpi.suaempresa.com"
$env:GLPI_API_PATH = "/apirest.php"
$env:GLPI_APP_TOKEN = "COLOQUE_SEU_APP_TOKEN"
$env:GLPI_USER_TOKEN = "COLOQUE_SEU_USER_TOKEN"
$env:MCP_TRANSPORT = "stdio"
python -m server
```
### Linux e macOS
```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt
```
Defina as variáveis de ambiente (ou carregue-as com uma ferramenta local apropriada) e inicie:
```bash
export GLPI_URL="https://glpi.suaempresa.com"
export GLPI_API_PATH="/apirest.php"
export GLPI_APP_TOKEN="COLOQUE_SEU_APP_TOKEN"
export GLPI_USER_TOKEN="COLOQUE_SEU_USER_TOKEN"
export MCP_TRANSPORT="stdio"
python -m server
```
Quando o servidor estiver no modo `stdio`, ele é iniciado pelo cliente MCP. Não é necessário abrir uma porta de rede nem manter um terminal separado executando o processo.
## Executar com Docker
Certifique-se de que o arquivo `.env` esteja preenchido. Construa a imagem na raiz do repositório:
```bash
docker build -t glpi-mcp:local .
```
### Modo stdio (cliente local)
O cliente MCP deve iniciar o contêiner e manter a entrada padrão aberta:
```bash
docker run --rm -i --env-file .env glpi-mcp:local
```
Esse comando é apropriado para ser usado como processo iniciado pelo cliente MCP. Não acrescente `-t` nessa configuração.
### Modo Streamable HTTP (serviço)
Para executar o servidor como serviço HTTP, configure `MCP_TRANSPORT=streamable-http` e faça o processo escutar em `0.0.0.0` dentro do contêiner. Exemplo:
```bash
docker run -d \
--name glpi-mcp \
--restart unless-stopped \
--env-file .env \
-e MCP_TRANSPORT=streamable-http \
-e MCP_HOST=0.0.0.0 \
-p 127.0.0.1:8000:8000 \
glpi-mcp:local
```
O mapeamento acima disponibiliza a porta somente no loopback do host. Para acesso remoto, coloque um proxy reverso na frente do serviço, configure HTTPS e autenticação/autorização no proxy. O endpoint MCP é:
```text
https://SEU-DOMINIO/mcp
```
Consulte os logs e pare o contêiner com:
```bash
docker logs -f glpi-mcp
docker stop glpi-mcp
```
Se alterar o código ou as dependências, reconstrua a imagem e recrie o contêiner.
## Conectar a um cliente MCP
### Claude Desktop — execução local com Python
No arquivo de configuração do Claude Desktop, adicione uma entrada em `mcpServers`. Ajuste o caminho absoluto do repositório e o caminho do arquivo `.env`:
```json
{
"mcpServers": {
"glpi": {
"command": "C:\\CAMINHO\\PARA\\glpi-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "server"],
"cwd": "C:\\CAMINHO\\PARA\\glpi-mcp",
"env": {
"GLPI_URL": "https://glpi.suaempresa.com",
"GLPI_API_PATH": "/apirest.php",
"GLPI_APP_TOKEN": "SEU_APP_TOKEN",
"GLPI_USER_TOKEN": "SEU_USER_TOKEN",
"MCP_TRANSPORT": "stdio"
}
}
}
}
```
Substitua os caminhos e credenciais pelos valores do seu ambiente. Alternativamente, use um pequeno script de inicialização que carregue o arquivo `.env` e inicie `python -m server`; não presuma que o cliente MCP carregará automaticamente o arquivo `.env`.
### Claude Desktop — execução local com Docker
Se a imagem já foi construída e o arquivo `.env` está em um caminho conhecido, a configuração pode iniciar o contêiner:
```json
{
"mcpServers": {
"glpi": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--env-file", "C:\\CAMINHO\\PARA\\glpi-mcp\\.env",
"glpi-mcp:local"
]
}
}
}
```
### Cliente remoto via Streamable HTTP
Quando o servidor estiver publicado com HTTPS e protegido por autenticação, configure o cliente MCP para usar o endpoint remoto `https://SEU-DOMINIO/mcp`. A forma exata de cadastrar um servidor HTTP varia conforme o cliente. Não use HTTP sem TLS em redes não confiáveis.
Após conectar, confirme no cliente se as ferramentas do GLPI foram carregadas. Reinicie o cliente após alterar sua configuração.
## Ferramentas disponíveis
| Ferramenta | Finalidade |
|---|---|
| `glpi_search(itemtype, criteria, limit)` | Pesquisa registros por tipo de item, critérios e limite de resultados. O limite máximo é 100. |
| `glpi_get_item(itemtype, item_id)` | Consulta um registro pelo tipo e ID. |
| `glpi_create_ticket(name, content, urgency, ...)` | Cria um chamado no GLPI. |
| `glpi_update_ticket(ticket_id, fields)` | Atualiza campos de um chamado existente. |
Os tipos de item, critérios de pesquisa e campos aceitos seguem as regras da API GLPI e as permissões da conta utilizada.
## Testes automatizados
Os testes usam `unittest` e mocks para isolar as chamadas HTTP. Não é necessário ter uma instância GLPI nem fornecer credenciais reais.
```bash
python -m pip install -r requirements.txt
python -m unittest discover -s tests -v
```
O GitHub Actions executa a suíte em Python 3.11 e 3.12 nos eventos configurados no workflow do repositório.
## Solução de problemas
| Sintoma | O que verificar |
|---|---|
| Erro de conexão com o GLPI | Confirme `GLPI_URL`, DNS, conectividade, firewall e se a API está acessível. |
| HTTP 401 ou 403 | Confira App-Token, token/credenciais do usuário, configuração da API e permissões da conta no GLPI. |
| Erro de certificado TLS | Instale/configure a cadeia de certificados confiável. Use `GLPI_VERIFY_TLS=false` somente em ambiente de desenvolvimento controlado. |
| Cliente não encontra o servidor | Em stdio, valide comando, argumentos, diretório de trabalho e caminhos absolutos. Reinicie o cliente depois de editar a configuração. |
| Contêiner HTTP inicia, mas não aceita conexões | Confirme `MCP_TRANSPORT=streamable-http`, `MCP_HOST=0.0.0.0), o mapeamento da porta e os logs do contêiner. |
| Ferramentas não aparecem | Consulte os logs do processo MCP e confirme que o cliente suporta o transporte configurado. |
## Segurança
- Use uma conta técnica dedicada no GLPI e aplique o princípio do menor privilégio.
- Nunca versione `.env`, tokens, senhas ou arquivos com credenciais.
- Mantenha a validação TLS habilitada em produção.
- Não exponha o endpoint MCP diretamente à Internet sem uma camada de autenticação e autorização.
- HTTPS protege o tráfego, mas, por si só, não identifica nem autoriza quem pode invocar as ferramentas.
- Revogue e gere novamente qualquer token que tenha sido exposto.
## Licença
Este projeto é distribuído sob a licença MIT. Consulte o arquivo [LICENSE](LICENSE) para ver os termos completos.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues