Cumulocity MCP Server

Acesse a plataforma Cumulocity IoT para gerenciar dispositivos, medições e alarmes.

Documentação

Servidor MCP Cumulocity

Um servidor baseado em Python que fornece funcionalidades da plataforma Cumulocity IoT através da interface MCP (Model Control Protocol). Este servidor permite interação perfeita com o gerenciamento de dispositivos, medições e sistemas de alarme da Cumulocity.

Ferramentas Disponíveis

Gerenciamento de Dispositivos

Obter Dispositivos
- Listar e filtrar dispositivos
- Parâmetros:
  - type: Filtrar por tipo de dispositivo
  - name: Filtrar por nome do dispositivo
  - page_size: Resultados por página (máximo 2000)
  - current_page: Número da página
Obter Dispositivo por ID
- Recuperar informações detalhadas de um dispositivo específico
- Parâmetro:
  - device_id: Identificador do dispositivo
Obter Dispositivos Filhos
- Visualizar dispositivos filhos de um dispositivo específico
- Parâmetro:
  - device_id: Identificador do dispositivo pai
Obter Fragmentos do Dispositivo
- Acessar fragmentos do dispositivo e seus valores
- Parâmetro:
  - device_id: Identificador do dispositivo

Medições

Obter Medições do Dispositivo

Recuperar medições do dispositivo com filtro de tempo
Parâmetros:
- device_id: Identificador do dispositivo
- date_from: Data de início (formato ISO 8601)
- date_to: Data de término (formato ISO 8601)
- page_size: Número de medições a recuperar

Alarmes

Obter Alarmes Ativos

Monitorar alarmes ativos no sistema
Parâmetros:
- severity: Filtrar por nível de severidade
- page_size: Número de resultados a recuperar

Mapeador Dinâmico

avaliar_expressao_jsonata Avaliar uma expressão JSONata contra um objeto JSON fornecido.

Entrada: Um objeto JSON como string e uma string de expressão JSONata. Saída: Resultado da avaliação da expressão JSONata.

Instalação e Implantação

Instalação Local

Usando uv (recomendado)

Ao usar uv, nenhuma instalação específica é necessária para este pacote. Usaremos uvx para executar diretamente mcp-server-c8y.

Usando PIP

Alternativamente, você pode instalar mcp-server-c8y via pip:

pip install mcp-server-c8y

Após a instalação, você pode executá-lo como um script usando:

python -m mcp_server_c8y

Implantação no Tenant Cumulocity

Você pode implantar este servidor como um microsserviço Cumulocity para integração direta com seu tenant. Isso é feito enviando um pacote de implantação especial (mcp-server-c8y.zip) para seu tenant Cumulocity.

Construindo o Pacote de Implantação do Microsserviço

Certifique-se de ter Docker e zip instalados em seu sistema.
Execute o script de construção fornecido para criar o pacote de implantação:

./scripts/buildcontainer.sh

Isso irá:

Construir a imagem Docker para o microsserviço
Salvar a imagem como image.tar no diretório docker/
Empacotar image.tar e cumulocity.json em docker/mcp-server-c8y.zip

Implantando na Cumulocity

Faça login no seu tenant Cumulocity como usuário com permissões de implantação de microsserviços.
Navegue até Administração > Ecossistema > Microsserviços.
Clique em Adicionar microsserviço e envie o arquivo mcp-server-c8y.zip do diretório docker/.
Aguarde o microsserviço ser implantado e iniciado. Você deve ver seu status como "Disponível" quando estiver pronto.
O microsserviço será acessível sob a URL de serviço do seu tenant, tipicamente: https://<your-tenant>.cumulocity.com/service/mcp-server-c8y/mcp/

Para mais detalhes sobre implantação de microsserviços Cumulocity, consulte a documentação oficial.

Uso com Claude Desktop

Este MCP Server pode ser usado com Claude Desktop para permitir que Claude interaja com sua plataforma Cumulocity IoT. Siga estes passos para configurá-lo:

Baixe e instale Claude Desktop
Configure o Claude Desktop para usar este MCP Server:
- Abra o Claude Desktop
- Clique no menu Claude e selecione "Configurações..."
- Navegue até "Desenvolvedor" na barra esquerda
- Clique em "Editar Configuração"
Adicione a seguinte configuração ao seu claude_desktop_config.json:

Usando uvx

"mcpServers": {
  "mcp-c8y": {
    "command": "uvx",
    "args": [
      "mcp-server-c8y",
      "--transport",
      "stdio"
    ],
    "env": {
      "C8Y_BASEURL": "https://your-cumulocity-instance.com",
      "C8Y_TENANT": "your-tenant-id",
      "C8Y_USER": "<your-username>",
      "C8Y_PASSWORD": "<your-password>"
    }
  }
}

Substitua os seguintes espaços reservados pelos seus valores reais:

https://your-cumulocity-instance.com: URL da sua instância Cumulocity
your-tenant-id: ID do seu tenant Cumulocity
your-username: Seu nome de usuário Cumulocity
your-password: Sua senha Cumulocity

Reinicie o Claude Desktop
Agora você deve ver um ícone de martelo no canto inferior direito da caixa de entrada. Clique nele para ver as ferramentas Cumulocity disponíveis.

Para informações mais detalhadas sobre o uso de MCP Servers com Claude Desktop, visite a documentação oficial do MCP.

Exemplo de Configurações do MCP Server no Cursor

Se você está usando Cursor e implantou seu MCP Server em um tenant Cumulocity, você pode configurar sua conexão MCP server com um arquivo .cursor/mcp.json. Exemplo (com dados sensíveis anonimizados):

{
  "mcpServers": {
    "Cumulocity": {
      "url": "https://your-cumulocity-instance.com/service/mcp-server-c8y/mcp/",
      "headers": {
        "Authorization": "Basic <YOUR_BASE64_AUTH_TOKEN>"
      }
    }
  }
}

https://your-cumulocity-instance.com: URL da sua instância Cumulocity
Substitua <YOUR_BASE64_AUTH_TOKEN> pelas suas credenciais reais codificadas em Base64. Nunca envie credenciais reais para controle de versão.

Contribuindo

Aceitamos contribuições de todos! Veja como você pode contribuir para este projeto:

Faça um fork do repositório
Crie um novo branch para sua funcionalidade ou correção de bug
Faça suas alterações seguindo estas boas práticas:
- Escreva mensagens de commit claras e descritivas
- Siga o estilo e as convenções de código existentes
- Adicione testes para novas funcionalidades
- Atualize a documentação conforme necessário
- Garanta que todos os testes passem
Envie um pull request