convez.ai
MCP ServerDados & AnalyticsIntermediário
influxdata

InfluxDB 3 MCP Server

influxdata/influxdb3_mcp_server

Integre InfluxDB 3 com Claude para queries, escrita de dados e gestão

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que integra InfluxDB 3 com clientes Claude, fornecendo ferramentas para escrever dados via line protocol, executar consultas SQL, gerenciar bancos de dados e tokens. Suporta todas as variantes do InfluxDB 3 (Core, Enterprise, Cloud Serverless, Cloud Dedicated e Clustered) com funcionalidades específicas para cada versão.

Instalação

$npx convez-ai influxdata/influxdb3_mcp_server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
38
Forks
14
Acompanhando
0
Saúde
50%
Último commit
há 2 dias
Versão
v2.0.1
Issues abertas
20
Contribuidores
12

Casos de uso

  • Executar consultas SQL contra dados de séries temporais via conversação
  • Escrever e ingerir dados em InfluxDB usando line protocol programaticamente
  • Gerenciar bancos de dados e tokens de autenticação sem sair do contexto Claude
  • Obter schema e measurements para análise interativa de dados

Veredito

MCP server robusto e bem mantido pela InfluxData, com suporte completo às variantes do InfluxDB 3. Ideal para pipelines de análise de dados e ingestão automatizada integrados a Claude, embora requeira configuração prévia de credenciais e infraestrutura InfluxDB.

README

A tradução para o português deste README ainda está na fila.

InfluxDB MCP Server

CI

Trust Score

Model Context Protocol (MCP) server for InfluxDB 3 integration. Provides tools, resources, and prompts for interacting with InfluxDB v3 (Core/Enterprise/Cloud Dedicated/Clustered/Cloud Serverless) via MCP clients.


Prerequisites

  • InfluxDB 3 Instance: URL and token (Core/Enterprise/Cloud Serverless) or Cluster ID and tokens (Cloud Dedicated/Clustered)
  • Node.js: v20.11 or newer (for npm/npx usage)
  • npm: v9 or newer (for npm/npx usage)
  • Docker: (for Docker-based setup)

Available Tools

Tool NameDescriptionAvailability
load_database_contextLoad optional custom database context and documentationAll versions
get_helpGet help and troubleshooting guidance for InfluxDB operationsAll versions
write_line_protocolWrite data using InfluxDB line protocolAll versions
create_databaseCreate a new database (with cloud-specific config options)All versions
update_databaseUpdate database configuration (retention for all; maxTables/maxColumns for Cloud Dedicated/Clustered)All versions
delete_databaseDelete a database by name (irreversible)All versions
execute_queryRun a SQL query against a database (supports multiple formats)All versions
get_measurementsList all measurements (tables) in a databaseAll versions
get_measurement_schemaGet schema (columns/types) for a measurement/tableAll versions
create_admin_tokenCreate a new admin token (full permissions)Core/Enterprise only
list_admin_tokensList all admin tokens (with optional filtering)Core/Enterprise only
create_resource_tokenCreate a resource token for specific DBs and permissionsCore/Enterprise only
list_resource_tokensList all resource tokens (with filtering and ordering)Core/Enterprise only
delete_tokenDelete a token by nameCore/Enterprise only
regenerate_operator_tokenRegenerate the operator token (dangerous/irreversible)Core/Enterprise only
cloud_list_database_tokensList all database tokens for Cloud-Dedicated/Clustered clusterCloud Dedicated/Clustered
cloud_get_database_tokenGet details of a specific database token by IDCloud Dedicated/Clustered
cloud_create_database_tokenCreate a new database token for Cloud-Dedicated/Clustered clusterCloud Dedicated/Clustered
cloud_update_database_tokenUpdate an existing database tokenCloud Dedicated/Clustered
cloud_delete_database_tokenDelete a database token from Cloud-Dedicated/Clustered clusterCloud Dedicated/Clustered
list_databasesList all available databases in the instanceAll versions
health_checkCheck InfluxDB connection and health statusAll versions

Available Resources

Resource NameDescription
influx-configRead-only access to InfluxDB configuration
influx-statusReal-time connection and health status
influx-databasesList of all databases in the instance
context-fileCustom user-provided database context and documentation

Available Prompts

Prompt NameDescription
list-databasesGenerate a prompt to list all available databases
check-healthGenerate a prompt to check InfluxDB health status
load-contextLoad custom database context and documentation

Setup & Integration Guide

1. Environment Variables

For Core/Enterprise InfluxDB:

You must provide:

  • INFLUX_DB_INSTANCE_URL (e.g. http://localhost:8181/)
  • INFLUX_DB_TOKEN
  • INFLUX_DB_PRODUCT_TYPE (core or enterprise)

Example .env:

INFLUX_DB_INSTANCE_URL=http://localhost:8181/
INFLUX_DB_TOKEN=your_influxdb_token_here
INFLUX_DB_PRODUCT_TYPE=core

For Cloud Serverless InfluxDB:

You must provide:

  • INFLUX_DB_INSTANCE_URL (e.g. https://us-east-1-1.aws.cloud2.influxdata.com)
  • INFLUX_DB_TOKEN
  • INFLUX_DB_PRODUCT_TYPE (cloud-serverless)

Example .env:

INFLUX_DB_INSTANCE_URL=https://us-east-1-1.aws.cloud2.influxdata.com
INFLUX_DB_TOKEN=your_influxdb_token_here
INFLUX_DB_PRODUCT_TYPE=cloud-serverless

For Cloud Dedicated InfluxDB:

You must provide INFLUX_DB_PRODUCT_TYPE=cloud-dedicated and INFLUX_DB_CLUSTER_ID, plus one of these token combinations:

Option 1: Database Token Only (Query/Write operations only):

INFLUX_DB_PRODUCT_TYPE=cloud-dedicated
INFLUX_DB_CLUSTER_ID=your_cluster_id_here
INFLUX_DB_TOKEN=your_database_token_here

Option 2: Management Token Only (Database management only):

INFLUX_DB_PRODUCT_TYPE=cloud-dedicated
INFLUX_DB_CLUSTER_ID=your_cluster_id_here
INFLUX_DB_ACCOUNT_ID=your_account_id_here
INFLUX_DB_MANAGEMENT_TOKEN=your_management_token_here

Option 3: Both Tokens (Full functionality):

INFLUX_DB_PRODUCT_TYPE=cloud-dedicated
INFLUX_DB_CLUSTER_ID=your_cluster_id_here
INFLUX_DB_ACCOUNT_ID=your_account_id_here
INFLUX_DB_TOKEN=your_database_token_here
INFLUX_DB_MANAGEMENT_TOKEN=your_management_token_here

For Clustered InfluxDB:

You must provide INFLUX_DB_PRODUCT_TYPE=clustered and INFLUX_DB_INSTANCE_URL, plus one of these token combinations:

Option 1: Database Token Only (Query/Write operations only):

INFLUX_DB_PRODUCT_TYPE=clustered
INFLUX_DB_INSTANCE_URL=https://your_cluster_host.com
INFLUX_DB_TOKEN=your_database_token_here

Option 2: Management Token Only (Database management only):

INFLUX_DB_PRODUCT_TYPE=clustered
INFLUX_DB_INSTANCE_URL=https://your_cluster_host.com
INFLUX_DB_MANAGEMENT_TOKEN=your_management_token_here

Option 3: Both Tokens (Full functionality):

INFLUX_DB_PRODUCT_TYPE=clustered
INFLUX_DB_INSTANCE_URL=https://your_cluster_host.com
INFLUX_DB_TOKEN=your_database_token_here
INFLUX_DB_MANAGEMENT_TOKEN=your_management_token_here

See corresponding env.<instancetype>.example for examples and detailed info.


2. Integration with MCP Clients

A. Local (npm install & run)

  1. Install dependencies:
    npm install
    
  2. Build the server:
    npm run build
    
  3. Configure your MCP client to use the built server. Example (see example-local.mcp.json):
    {
      "mcpServers": {
        "influxdb": {
          "command": "node",
          "args": ["/path/to/influx-mcp-standalone/build/index.js"],
          "env": {
            "INFLUX_DB_INSTANCE_URL": "http://localhost:8181/",
            "INFLUX_DB_TOKEN": "<YOUR_INFLUXDB_TOKEN>",
            "INFLUX_DB_PRODUCT_TYPE": "core"
          }
        }
      }
    }
    

B. Local (npx, no install/build required)

  1. Run directly with npx (after publishing to npm, won't work yet):
    {
      "mcpServers": {
        "influxdb": {
          "command": "npx",
          "args": ["-y", "@influxdata/influxdb3-mcp-server"],
          "env": {
            "INFLUX_DB_INSTANCE_URL": "http://localhost:8181/",
            "INFLUX_DB_TOKEN": "<YOUR_INFLUXDB_TOKEN>",
            "INFLUX_DB_PRODUCT_TYPE": "core"
          }
        }
      }
    }
    

C. Docker

Before running the Docker integration, you must build the Docker image:

# Option 1: Use docker compose (recommended)
docker compose build
# Option 2: Use npm script
npm run docker:build

a) Docker with remote InfluxDB instance (see example-docker.mcp.json):

{
  "mcpServers": {
    "influxdb": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "INFLUX_DB_INSTANCE_URL",
        "-e",
        "INFLUX_DB_TOKEN",
        "-e",
        "INFLUX_DB_PRODUCT_TYPE",
        "mcp/influxdb"
      ],
      "env": {
        "INFLUX_DB_INSTANCE_URL": "http://remote-influxdb-host:8181/",
        "INFLUX_DB_TOKEN": "<YOUR_INFLUXDB_TOKEN>",
        "INFLUX_DB_PRODUCT_TYPE": "core"
      }
    }
  }
}

b) Docker with InfluxDB running in Docker on the same machine (see example-docker.mcp.json):

Use host.docker.internal as the InfluxDB URL so the MCP server container can reach the InfluxDB container:

{
  "mcpServers": {
    "influxdb": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--add-host=host.docker.internal:host-gateway",
        "-e",
        "INFLUX_DB_INSTANCE_URL",
        "-e",
        "INFLUX_DB_TOKEN",
        "-e",
        "INFLUX_DB_PRODUCT_TYPE",
        "influxdb-mcp-server"
      ],
      "env": {
        "INFLUX_DB_INSTANCE_URL": "http://host.docker.internal:8181/",
        "INFLUX_DB_TOKEN": "<YOUR_INFLUXDB_TOKEN>",
        "INFLUX_DB_PRODUCT_TYPE": "enterprise"
      }
    }
  }
}

Example Usage

  • Use your MCP client to call tools, resources, or prompts as described above.
  • Custom Context: Edit the provided context/database-context.md file or remove it and create your own context file with "context" in the name (.json, .txt, .md) to provide database documentation. Use the load_database_context tool or load-context prompt to access it.
  • See the example-*.mcp.json files for ready-to-use configuration templates:
    • example-local.mcp.json - Local development setup
    • example-npx.mcp.json - NPX-based setup
    • example-docker.mcp.json - Docker-based setup
    • example-cloud-dedicated.mcp.json - Cloud Dedicated with all variables
    • example-clustered.mcp.json - Clustered with all variables
    • example-cloud-serverless.mcp.json - Cloud Serverless configuration
  • See the env.example, env.cloud-dedicated.example, env.clustered.example, and env.cloud-serverless.example files for environment variable templates.

Database Retention Policy Examples

Core/Enterprise - Set 90-day Retention

// Set 90-day retention policy on Enterprise instance
await mcp.update_database({
  name: "my_database",
  retentionPeriod: 7776000000000000, // 90 days in nanoseconds
});

Cloud Dedicated - Update Multiple Settings

// Update retention, maxTables, and maxColumnsPerTable
await mcp.update_database({
  name: "my_database",
  retentionPeriod: 7776000000000000, // 90 days
  maxTables: 1000,
  maxColumnsPerTable: 250,
});

Common Retention Periods

DurationNanoseconds
7 days604,800,000,000,000
30 days2,592,000,000,000,000
90 days7,776,000,000,000,000
180 days15,552,000,000,000,000
1 year31,536,000,000,000,000

Support & Troubleshooting

  • Use the get_help tool for built-in help and troubleshooting.
  • For connection issues, check your environment variables and InfluxDB instance status.
  • For advanced configuration, see the comments in the example .env and MCP config files.

License

MIT

Ver o original no GitHub

Bom para

Relacionados