InfluxDB MCP Server

InfluxDB v2 MCP Server

Un servidor de Model Context Protocol (MCP) que expone acceso a una instancia de InfluxDB v2 utilizando la API OSS v2 de InfluxDB. Construido principalmente con Claude Code.

Características

Este servidor MCP proporciona:

• Recursos: Acceso a datos de organizaciones, buckets y mediciones
• Herramientas: Escribir datos, ejecutar consultas y gestionar objetos de base de datos
• Prompts: Plantillas para consultas Flux comunes y formato Line Protocol

Recursos

El servidor expone los siguientes recursos:

1. Lista de organizaciones: influxdb://orgs

   • Muestra todas las organizaciones en la instancia de InfluxDB

2. Lista de buckets: influxdb://buckets

   • Muestra todos los buckets con sus metadatos

3. Mediciones de bucket: influxdb://bucket/{bucketName}/measurements

   • Lista todas las mediciones dentro de un bucket especificado

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

   • Ejecuta una consulta Flux y devuelve los resultados como un recurso

Herramientas

El servidor proporciona estas herramientas:

1. write-data: Escribir datos de series temporales en formato line protocol

   • Parámetros: org, bucket, data, precision (opcional)

2. query-data: Ejecutar consultas Flux

   • Parámetros: org, query

3. create-bucket: Crear un nuevo bucket

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

4. create-org: Crear una nueva organización

   • Parámetros: name, description (opcional)

Prompts

El servidor ofrece estas plantillas de prompts:

1. flux-query-examples: Ejemplos comunes de consultas Flux
2. line-protocol-guide: Guía del formato line protocol de InfluxDB

Configuración

El servidor requiere estas variables de entorno:

• INFLUXDB_TOKEN (obligatorio): Token de autenticación para la API de InfluxDB
• INFLUXDB_URL (opcional): URL de la instancia de InfluxDB (por defecto http://localhost:8086)
• INFLUXDB_ORG (opcional): Nombre de organización predeterminado para ciertas operaciones

Instalación

Instalación mediante Smithery

Para instalar InfluxDB MCP Server para Claude Desktop automáticamente mediante Smithery:

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

Opción 1: Ejecutar con npx (recomendado)

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

Opción 2: Instalar globalmente

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

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

Opción 3: Desde el código fuente

# 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 utiliza transporte stdio por defecto. Puedes solicitarlo explícitamente con --stdio, o iniciar el servidor con transporte HTTP Streamable proporcionando la opción --http con un número de puerto opcional (por defecto 3000). Este modo utiliza un 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

Si instalaste globalmente o estás usando npx, puedes ejecutar:

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

Integración con Claude for Desktop

Añade el servidor a tu 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"
      }
    }
  }
}

Si se instaló 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"
      }
    }
  }
}

Estructura del código

El código del servidor está organizado en una estructura modular:

• src/
  • index.js - Punto de entrada principal del servidor
  • config/ - Archivos relacionados con la configuración
    • env.js - Manejo de variables de entorno
  • utils/ - Funciones de utilidad
    • influxClient.js - Cliente de la API de InfluxDB
    • loggerConfig.js - Configuración del registrador de consola
  • handlers/ - Manejadores de recursos y herramientas
    • organizationsHandler.js - Listado de organizaciones
    • bucketsHandler.js - Listado de buckets
    • measurementsHandler.js - Listado de mediciones
    • queryHandler.js - Ejecución de consultas
    • writeDataTool.js - Herramienta de escritura de datos
    • queryDataTool.js - Herramienta de consulta
    • createBucketTool.js - Herramienta de creación de buckets
    • createOrgTool.js - Herramienta de creación de organizaciones
  • prompts/ - Plantillas de prompts
    • fluxQueryExamplesPrompt.js - Ejemplos de consultas Flux
    • lineProtocolGuidePrompt.js - Guía de line protocol

Esta estructura permite un mejor mantenimiento, pruebas más fáciles y una separación de responsabilidades más clara.

Pruebas

El repositorio incluye pruebas de integración exhaustivas que:

• Levantan un contenedor Docker con InfluxDB
• Lo pueblan con datos de ejemplo
• Prueban toda la funcionalidad del servidor MCP

Para ejecutar las pruebas:

npm test

Licencia

MIT