InfluxDB MCP Server

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 Name	Description	Availability
`load_database_context`	Load optional custom database context and documentation	All versions
`get_help`	Get help and troubleshooting guidance for InfluxDB operations	All versions
`write_line_protocol`	Write data using InfluxDB line protocol	All versions
`create_database`	Create a new database (with cloud-specific config options)	All versions
`update_database`	Update database configuration (retention for all; maxTables/maxColumns for Cloud Dedicated/Clustered)	All versions
`delete_database`	Delete a database by name (irreversible)	All versions
`execute_query`	Run a SQL query against a database (supports multiple formats)	All versions
`get_measurements`	List all measurements (tables) in a database	All versions
`get_measurement_schema`	Get schema (columns/types) for a measurement/table	All versions
`create_admin_token`	Create a new admin token (full permissions)	Core/Enterprise only
`list_admin_tokens`	List all admin tokens (with optional filtering)	Core/Enterprise only
`create_resource_token`	Create a resource token for specific DBs and permissions	Core/Enterprise only
`list_resource_tokens`	List all resource tokens (with filtering and ordering)	Core/Enterprise only
`delete_token`	Delete a token by name	Core/Enterprise only
`regenerate_operator_token`	Regenerate the operator token (dangerous/irreversible)	Core/Enterprise only
`cloud_list_database_tokens`	List all database tokens for Cloud-Dedicated/Clustered cluster	Cloud Dedicated/Clustered
`cloud_get_database_token`	Get details of a specific database token by ID	Cloud Dedicated/Clustered
`cloud_create_database_token`	Create a new database token for Cloud-Dedicated/Clustered cluster	Cloud Dedicated/Clustered
`cloud_update_database_token`	Update an existing database token	Cloud Dedicated/Clustered
`cloud_delete_database_token`	Delete a database token from Cloud-Dedicated/Clustered cluster	Cloud Dedicated/Clustered
`list_databases`	List all available databases in the instance	All versions
`health_check`	Check InfluxDB connection and health status	All versions

Available Resources

Resource Name	Description
`influx-config`	Read-only access to InfluxDB configuration
`influx-status`	Real-time connection and health status
`influx-databases`	List of all databases in the instance
`context-file`	Custom user-provided database context and documentation

Available Prompts

Prompt Name	Description
`list-databases`	Generate a prompt to list all available databases
`check-health`	Generate a prompt to check InfluxDB health status
`load-context`	Load 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:

hljs language-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:

hljs language-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):

hljs language-env

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):

hljs language-env

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):

hljs language-env

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):

hljs language-env

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):

hljs language-env

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):

hljs language-env

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)

Install dependencies:
hljs language-bash
```
npm install
```
Build the server:
hljs language-bash
```
npm run build
```

Configure your MCP client to use the built server. Example (see example-local.mcp.json):

hljs language-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)

Run directly with npx (after publishing to npm, won't work yet):

hljs language-json

{
  "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:

hljs language-bash

# 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):

hljs language-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:

hljs language-json

{
  "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

hljs language-typescript

// 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

hljs language-typescript

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

Common Retention Periods

Duration	Nanoseconds
7 days	604,800,000,000,000
30 days	2,592,000,000,000,000
90 days	7,776,000,000,000,000
180 days	15,552,000,000,000,000
1 year	31,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

influxdb3_mcp_server

InfluxDB MCP Server

Prerequisites

Available Tools

Available Resources

Available Prompts

Setup & Integration Guide

1. Environment Variables

For Core/Enterprise InfluxDB:

For Cloud Serverless InfluxDB:

For Cloud Dedicated InfluxDB:

For Clustered InfluxDB:

2. Integration with MCP Clients

A. Local (npm install & run)

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

C. Docker

Example Usage

Database Retention Policy Examples

Core/Enterprise - Set 90-day Retention

Cloud Dedicated - Update Multiple Settings

Common Retention Periods

Support & Troubleshooting

License

Similar Packages

Security

Original Author

Publisher