InfluxDB MCP Server

Servidor MCP InfluxDB v2

Um servidor Model Context Protocol (MCP) que expõe acesso a uma instância InfluxDB v2 usando a API OSS v2 do InfluxDB. Construído principalmente com Claude Code.

Recursos

Este servidor MCP fornece:

• Recursos: Acesso a dados de organização, bucket e medição
• Ferramentas: Escrever dados, executar consultas e gerenciar objetos do banco de dados
• Prompts: Modelos para consultas Flux comuns e formato Line Protocol

Recursos

O servidor expõe os seguintes recursos:

1. Lista de Organizações: influxdb://orgs

   • Exibe todas as organizações na instância InfluxDB

2. Lista de Buckets: influxdb://buckets

   • Mostra todos os buckets com seus metadados

3. Medições do Bucket: influxdb://bucket/{bucketName}/measurements

   • Lista todas as medições dentro de um bucket especificado

4. Consultar Dados: influxdb://query/{orgName}/{fluxQuery}

   • Executa uma consulta Flux e retorna os resultados como um recurso

Ferramentas

O servidor fornece estas ferramentas:

1. write-data: Escrever dados de série temporal em formato line protocol

   • Parâmetros: org, bucket, data, precisão (opcional)

2. query-data: Executar consultas Flux

   • Parâmetros: org, query

3. create-bucket: Criar um novo bucket

   • Parâmetros: name, orgID, retentionPeriodSeconds (opcional)

4. create-org: Criar uma nova organização

   • Parâmetros: name, description (opcional)

Prompts

O servidor oferece estes modelos de prompt:

1. flux-query-examples: Exemplos de consultas Flux comuns
2. line-protocol-guide: Guia para o formato line protocol do InfluxDB

Configuração

O servidor requer estas variáveis de ambiente:

• INFLUXDB_TOKEN (obrigatório): Token de autenticação para a API do InfluxDB
• INFLUXDB_URL (opcional): URL da instância InfluxDB (padrão: http://localhost:8086)
• INFLUXDB_ORG (opcional): Nome da organização padrão para certas operações

Instalação

Instalando via Smithery

Para instalar o InfluxDB MCP Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @idoru/influxdb-mcp-server --client claude

Opção 1: Executar com npx (recomendado)

# Run directly with npx
INFLUXDB_TOKEN=your_token npx influxdb-mcp-server

Opção 2: Instalar globalmente

# Install globally
npm install -g influxdb-mcp-server

# Run the server
INFLUXDB_TOKEN=your_token influxdb-mcp-server

Opção 3: A partir do código-fonte

# Clone the repository
git clone https://github.com/idoru/influxdb-mcp-server.git
cd influxdb-mcp-server

# Install dependencies
npm install

# Run the server
INFLUXDB_TOKEN=your_token npm start

influxdb-mcp-server usa transporte stdio por padrão. Você pode solicitá-lo explicitamente com --stdio, ou iniciar o servidor com transporte HTTP Streamable fornecendo a opção --http com um número de porta opcional (padrão: 3000). Este modo usa um servidor Express.js interno:

# Start with Streamable HTTP transport on default port 3000
INFLUXDB_TOKEN=your_token npm start -- --http

# Start with Streamable HTTP transport on a specific port
INFLUXDB_TOKEN=your_token npm start -- --http 8080

Se você instalou globalmente ou está usando npx, pode executar:

INFLUXDB_TOKEN=your_token influxdb-mcp-server --http
# or explicitly force stdio
INFLUXDB_TOKEN=your_token influxdb-mcp-server --stdio
# or
INFLUXDB_TOKEN=your_token influxdb-mcp-server --http 8080

Integração com Claude for Desktop

Adicione o servidor ao seu claude_desktop_config.json:

Usando npx (recomendado)

{
  "mcpServers": {
    "influxdb": {
      "command": "npx",
      "args": ["influxdb-mcp-server"],
      "env": {
        "INFLUXDB_TOKEN": "your_token",
        "INFLUXDB_URL": "http://localhost:8086",
        "INFLUXDB_ORG": "your_org"
      }
    }
  }
}

Se instalado localmente

{
  "mcpServers": {
    "influxdb": {
      "command": "node",
      "args": ["/path/to/influxdb-mcp-server/src/index.js"],
      "env": {
        "INFLUXDB_TOKEN": "your_token",
        "INFLUXDB_URL": "http://localhost:8086",
        "INFLUXDB_ORG": "your_org"
      }
    }
  }
}

Estrutura do Código

O código do servidor está organizado em uma estrutura modular:

• src/
  • index.js - Ponto de entrada principal do servidor
  • config/ - Arquivos relacionados à configuração
    • env.js - Manipulação de variáveis de ambiente
  • utils/ - Funções utilitárias
    • influxClient.js - Cliente da API InfluxDB
    • loggerConfig.js - Configuração do logger de console
  • handlers/ - Manipuladores de recursos e ferramentas
    • organizationsHandler.js - Listagem de organizações
    • bucketsHandler.js - Listagem de buckets
    • measurementsHandler.js - Listagem de medições
    • queryHandler.js - Execução de consultas
    • writeDataTool.js - Ferramenta de escrita de dados
    • queryDataTool.js - Ferramenta de consulta
    • createBucketTool.js - Ferramenta de criação de bucket
    • createOrgTool.js - Ferramenta de criação de organização
  • prompts/ - Modelos de prompt
    • fluxQueryExamplesPrompt.js - Exemplos de consultas Flux
    • lineProtocolGuidePrompt.js - Guia de line protocol

Esta estrutura permite melhor manutenibilidade, testes mais fáceis e separação mais clara de responsabilidades.

Testes

O repositório inclui testes de integração abrangentes que:

• Iniciam um contêiner Docker com InfluxDB
• Preenchem-no com dados de exemplo
• Testam toda a funcionalidade do servidor MCP

Para executar os testes:

npm test

Licença

MIT