Ubidots MCP Server

Servidor MCP que expõe dados, entidades e agregações de IoT da Ubidots para assistentes de IA.

Ver em ubidots.comExperimente este MCPPatrocinado

Documentação

Visão Geral

O Model Context Protocol (MCP) permite que aplicações de IA se conectem com segurança a APIs externas. Em projetos de IoT, isso significa que sua aplicação de IA pode decidir automaticamente se precisa chamar a API da Ubidots para responder a um prompt do usuário — seja para ler dados ou fazer uma alteração em seu nome.

Exemplos:

"Quais dispositivos estão offline?"
"Mostre os últimos valores de temperature para o dispositivo aws810."
"Qual foi a média de temperature ontem de Machine ABC."
"Crie um novo incidente para o dispositivo aws810\ com severidade P2."
"Atualize a descrição do dispositivo pump-04\."

Neste artigo, exploramos o uso do Ubidots MCP a partir de:

Claude Desktop
Anthropic API

Usando o servidor Ubidots MCP a partir do Claude Desktop

Pré-requisitos

Uma conta Ubidots e token de API Ubidots (com escopo para a organização que você deseja usar).
Claude Desktop instalado (macOS/Windows/Linux).

Passo a passo

Abra as Configurações do Claude Desktop
Inicie o Claude Desktop → Configurações → Desenvolvedor.
Edite a Configuração
Clique em Editar configuração para abrir claude_desktop_config.json.
Adicione a entrada do servidor Ubidots MCP
Cole o trecho abaixo no JSON (mescle com seu mcpServers existente, se houver).
Substitua <YOUR UBIDOTS TOKEN> pelo seu token real.
```
{
   "mcpServers": {
      "ubidots": {
         "command": "npx",
         "args": [
            "-y",
            "mcp-remote",
            "https://mcp.ubidots.com/mcp",
            "--header",
            "Authorization:${AUTH_HEADER}"
         ],
         "env": {
            "AUTH_HEADER": "Bearer <YOUR UBIDOTS TOKEN>"
         }
      }
   }
}
```
Observações
- Se mcpServers já existir, adicione apenas o bloco "ubidots" dentro dele.
- Mantenha a sintaxe JSON válida (vírgulas, chaves).
- A URL acima (/mcp) expõe todas as ferramentas disponíveis. Consulte Caminhos MCP com escopo abaixo para restringir o acesso por entidade ou nível de permissão.
Salve e Recarregue o Claude
Salve o arquivo e reinicie o Claude Desktop (ou use "Recarregar", se disponível).
Verifique a conexão Em uma nova conversa no Claude, certifique-se de que o MCP está habilitado e tente isto:
- "Quais dispositivos estão online?" Se configurado corretamente, o Claude deve confirmar que a ferramenta MCP está disponível e retornar dados ao vivo da Ubidots.

Solução de problemas

O Claude não mostra a ferramenta Ubidots

Reinicie o Claude após editar a configuração.
Verifique a validade do JSON (use um linter JSON online, se necessário).
Garanta que npx esteja disponível no PATH do seu sistema.

401 / Não autorizado

Verifique se o token não expirou ou foi revogado.

Erros de rede

Confirme que você está online e não atrás de um proxy/firewall que bloqueie HTTPS de saída.
Tente novamente mais tarde em caso de problemas de rede transitórios.

Vários servidores MCP configurados

Certifique-se de que não há chaves duplicadas chamadas ubidots.
Se você renomeou o servidor, lembre-se de que o nome que você verá dentro do Claude corresponderá a essa chave.

Atualizando ou Removendo a Integração

Atualizar token: Abra claude_desktop_config.json, substitua o token no cabeçalho, salve e recarregue o Claude.
Desativar: Remova ou comente o bloco "ubidots" sob mcpServers, salve e recarregue o Claude.

Usando o servidor Ubidots MCP com a Anthropic API

Embora o Claude Desktop seja ótimo para testes, ele não se assemelha a cenários do mundo real, onde os usuários desejarão interagir com um agente de IA por Slack, Whatsapp ou uma caixa de chat baseada na web dentro da sua aplicação alimentada pela Ubidots.

Nesses cenários, usar uma API de IA como a OpenAI API ou a Anthropic API permitirá que você adicione a camada de inteligência necessária ao seu caso de uso.

Aqui está um exemplo de solicitação que você usaria de tal aplicação para interagir tanto com as consultas dos seus usuários quanto com o Ubidots MCP:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-04-04" \
  -d '{
    "model": "claude-3-5-sonnet-20240620",
    "max_tokens": 500,
    "system": "You are a smart IoT assistant. If you need device data, use the attached MCP.",
    "messages": [
      {"role": "user", "content": "List my devices"}
    ],
    "mcp_servers": [
      {
        "type": "url",
        "name": "ubidots",
        "url": "https://mcp.ubidots.com/mcp",
        "authorization_token": "YOUR_UBIDOTS_TOKEN"
      }
    ]
  }'

Para saber mais sobre o conector MCP da Anthropic, visite a documentação oficial deles.

Caminhos MCP com escopo

Por padrão, conectar-se a https://mcp.ubidots.com/mcp expõe todas as ferramentas disponíveis à IA — incluindo ferramentas que criam ou modificam dados, não apenas leem. Você pode restringir isso usando um caminho mais específico — seja para limitar permissões (somente leitura) ou para limitar o escopo a uma entidade específica (dispositivos, variáveis, incidentes, etc.).

Isso é útil por dois motivos:

Segurança: Você pode garantir que a IA tenha apenas acesso de leitura, ou que ela só possa interagir com um subconjunto específico dos seus dados.
Prevenção de alterações não intencionais: Como a maioria das entidades agora suporta operações de escrita (criar ou atualizar registros), definir um escopo para um caminho /readonly\ é recomendado para qualquer caso de uso em que a IA não deva modificar sua conta — por exemplo, um chatbot de relatórios somente leitura.
Eficiência de tokens: Expor menos ferramentas significa que menos contexto é enviado ao modelo de IA em cada solicitação, reduzindo o consumo de tokens de entrada.

Caminhos disponíveis

Caminho	Descrição
`/mcp`	Todas as ferramentas (leitura e escrita) em todas as entidades
`/mcp/readonly`	Todas as ferramentas, restritas a operações somente leitura
`/mcp/_/devices`	Todas as ferramentas com escopo apenas para dispositivos
`/mcp/_/devices/readonly`	Ferramentas somente leitura com escopo apenas para dispositivos
`/mcp/_/variables`	Todas as ferramentas com escopo apenas para variáveis
`/mcp/_/variables/readonly`	Ferramentas somente leitura com escopo apenas para variáveis
`/mcp/_/device-groups`	Todas as ferramentas com escopo apenas para grupos de dispositivos
`/mcp/_/device-groups/readonly`	Ferramentas somente leitura com escopo apenas para grupos de dispositivos
`/mcp/_/device-types`	Todas as ferramentas com escopo apenas para tipos de dispositivos
`/mcp/_/device-types/readonly`	Ferramentas somente leitura com escopo apenas para tipos de dispositivos
`/mcp/_/organizations`	Todas as ferramentas com escopo apenas para organizações
`/mcp/_/organizations/readonly`	Ferramentas somente leitura com escopo apenas para organizações
`/mcp/_/events`	Todas as ferramentas com escopo apenas para eventos (atualmente somente leitura)
`/mcp/_/events/readonly`	Igual a `/mcp/_/events`; nenhuma ferramenta de escrita existe para esta entidade ainda
`/mcp/_/incidents`	Todas as ferramentas com escopo apenas para incidentes
`/mcp/_/incidents/readonly`	Ferramentas somente leitura com escopo apenas para incidentes

Exemplo: acesso somente leitura a dispositivos

Em uma configuração do Claude Desktop, basta substituir a URL:

"args": [
   "-y",
   "mcp-remote",
   "https://mcp.ubidots.com/mcp/_/devices/readonly",
   "--header",
   "Authorization:${AUTH_HEADER}"
]

Em uma chamada da Anthropic API:

"mcp_servers": [
  {
    "type": "url",
    "name": "ubidots",
    "url": "https://mcp.ubidots.com/mcp/_/devices/readonly",
    "authorization_token": "YOUR_UBIDOTS_TOKEN"
  }
]

FAQ

Isso funciona com outros clientes MCP?

Sim. Qualquer cliente compatível com MCP pode se conectar a https://mcp.ubidots.com/mcp (ou a qualquer um dos caminhos com escopo) usando o mesmo cabeçalho Authorization.

O servidor é local?
Não. O Ubidots MCP Server é hospedado na nuvem; isso evita que você precise executá-lo localmente e permite aplicações como bots de IA no Whatsapp.

Posso usar várias contas Ubidots?
Sim — crie entradas separadas (por exemplo, ubidots-prod, ubidots-staging) com tokens diferentes.

Ferramentas MCP

O servidor Ubidots MCP fornece acesso aos dados da sua conta nas entidades abaixo. A maioria das entidades suporta leitura e escrita — você pode consultar registros existentes, bem como criar e atualizá-los. Eventos atualmente é somente leitura.

Entidade	Ferramentas de leitura	Ferramentas de escrita
Dispositivos	`list_devices`, `list_device_last_values`	`create_device`, `update_device`
Variáveis	`list_variables`, `list_variables_by_device`, `get_variable_statistics`, `get_variable_series`	`create_variable`, `update_variable`
Tipos de Dispositivos	`list_device_types`	`create_device_type`, `update_device_type`
Grupos de Dispositivos	`list_device_groups`	`create_device_group`, `update_device_group`
Organizações	`list_organizations`	`create_organization`, `update_organization`
Eventos	`list_events`, `list_event_logs`	—
Incidentes	`list_incidents`, `list_incident_logs`	`create_incident`, `acknowledge_incident`, `add_incident_comment`, `assign_incident`

Observação sobre Incidentes: A atribuição e o estado de um incidente (reconhecido, comentado) podem ser atualizados após a criação, mas sua severidade e descrição atualmente não podem ser alteradas por meio do MCP depois de criados.

Lista de funções agregadas estatísticas que podem ser consultadas usando o servidor MCP

O servidor MCP pode calcular resultados agregados sobre variáveis do usuário usando as seguintes operações:

Primeiro
Último
Mínimo
Máximo
Contagem
Soma
Média
Desvio padrão
Percentil 25
Percentil 50
Percentil 75

Exemplos de Prompts para Começar

Lendo dados:

"Liste organizações e mostre contagens de dispositivos para cada uma."
"Para o dispositivo aws810, liste variáveis e mostre os últimos timestamps e valores."
"Qual é a temperatura média em que o ar-condicionado está operando em cada andar?"

Criando e atualizando dados:

"Crie um novo dispositivo chamado pump-04 sob a organização Plant North."
"Atualize a descrição do dispositivo aws810 para 'Compressor da ala norte'."
"Crie um incidente P2 para o dispositivo aws810 sobre uma falha de sensor."
"Reconheça o incidente #1234 e deixe um comentário de que estamos investigando."
"Mostre-me todos os incidentes acionados que não estão atribuídos a ninguém."

Se você encontrar problemas ou tiver solicitações de recursos para o Ubidots MCP Server, informe-nos qual cliente você está usando, seu sistema operacional e uma cópia editada da sua configuração mcpServers para que possamos ajudar mais rapidamente.