@influxdata/influxdb3-mcp-server 1.3.0

package/README.md

@@ -0,0 +1,318 @@
+# InfluxDB MCP Server
+
+[![CI](https://github.com/influxdata/influxdb3_mcp_server/actions/workflows/ci.yml/badge.svg)](https://github.com/influxdata/influxdb3_mcp_server/actions/workflows/ci.yml)
+<!-- [![Unit Tests](https://github.com/influxdata/influxdb3_mcp_server/actions/workflows/unit.yml/badge.svg)](https://github.com/influxdata/influxdb3_mcp_server/actions/workflows/unit.yml) -->
+<!-- [![Lint](https://github.com/influxdata/influxdb3_mcp_server/actions/workflows/lint.yml/badge.svg)](https://github.com/influxdata/influxdb3_mcp_server/actions/workflows/lint.yml) -->
+[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/influxdata/influxdb3_mcp_server)](https://archestra.ai/mcp-catalog/influxdata__influxdb3_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, etc.)                   | Cloud Dedicated/Clustered/Serverless |
+| `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`:
+
+```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`:
+
+```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):
+
+```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):
+
+```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):
+
+```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):
+
+```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):
+
+```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):
+
+```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)
+
+1. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+2. **Build the server:**
+   ```bash
+   npm run build
+   ```
+3. **Configure your MCP client** to use the built server. Example (see `example-local.mcp.json`):
+   ```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):
+   ```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:
+
+```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`):
+
+```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:
+
+```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.
+
+---
+
+## 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](LICENSE)

package/build/config.js

@@ -0,0 +1,85 @@
+/**
+ * MCP Server Configuration
+ *
+ * Handles environment variables and configuration for the standalone MCP server
+ */
+import dotenv from "dotenv";
+import { InfluxProductType } from "./helpers/enums/influx-product-types.enum.js";
+dotenv.config();
+/**
+ * Load configuration from environment variables
+ */
+export function loadConfig() {
+    return {
+        influx: {
+            url: process.env.INFLUX_DB_INSTANCE_URL,
+            token: process.env.INFLUX_DB_TOKEN ||
+                process.env.INFLUX_DB_DATABASE_TOKEN ||
+                undefined,
+            management_token: process.env.INFLUX_DB_MANAGEMENT_TOKEN || undefined,
+            type: process.env.INFLUX_DB_PRODUCT_TYPE || "unknown",
+            account_id: process.env.INFLUX_DB_ACCOUNT_ID,
+            cluster_id: process.env.INFLUX_DB_CLUSTER_ID,
+        },
+        server: {
+            name: "influxdb-mcp-server",
+            version: "1.3.0",
+        },
+    };
+}
+/**
+ * Validate that required configuration is present
+ */
+export function validateConfig(config) {
+    const errors = [];
+    if (!config.influx.type ||
+        ![
+            InfluxProductType.Enterprise,
+            InfluxProductType.Core,
+            InfluxProductType.CloudDedicated,
+            InfluxProductType.CloudServerless,
+            InfluxProductType.Clustered,
+        ].includes(config.influx.type)) {
+        errors.push(`INFLUX_DB_PRODUCT_TYPE is required and must be one of: ${InfluxProductType.Enterprise}, ${InfluxProductType.Core}, ${InfluxProductType.CloudDedicated}, ${InfluxProductType.CloudServerless}, ${InfluxProductType.Clustered}`);
+    }
+    if (config.influx.type === InfluxProductType.CloudDedicated) {
+        if (!config.influx.cluster_id) {
+            errors.push("INFLUX_DB_CLUSTER_ID is required for cloud-dedicated");
+        }
+        const hasQueryWrite = config.influx.cluster_id && config.influx.token;
+        const hasManagement = config.influx.cluster_id &&
+            config.influx.account_id &&
+            config.influx.management_token;
+        if (!hasQueryWrite && !hasManagement) {
+            errors.push("For cloud-dedicated, provide at least either: (CLUSTER_ID + DB TOKEN) for query/write, or (CLUSTER_ID + ACCOUNT_ID + MANAGEMENT TOKEN) for management API.");
+        }
+    }
+    else if (config.influx.type === InfluxProductType.Clustered) {
+        const hasQueryWrite = config.influx.token;
+        const hasManagement = config.influx.management_token;
+        config.influx.account_id = "11111111-1111-1111-1111-111111111111"; // Dummy account ID for clustered for compatibility with cloud-dedicated handlers
+        config.influx.cluster_id = "11111111-1111-1111-1111-111111111111"; // Dummy cluster ID for clustered for compatibility with cloud-dedicated handlers
+        if (!hasQueryWrite && !hasManagement) {
+            errors.push("For clustered, provide at least either: DB TOKEN for query/write, or MANAGEMENT TOKEN for management API.");
+        }
+    }
+    else if (config.influx.type === InfluxProductType.CloudServerless) {
+        if (!config.influx.url) {
+            errors.push("INFLUX_DB_INSTANCE_URL is required for cloud-serverless");
+        }
+        if (!config.influx.token) {
+            errors.push("INFLUX_DB_TOKEN is required for cloud-serverless");
+        }
+    }
+    else if ([InfluxProductType.Enterprise, InfluxProductType.Core].includes(config.influx.type)) {
+        if (!config.influx.url) {
+            errors.push("INFLUX_DB_INSTANCE_URL is required for core/enterprise");
+        }
+        if (!config.influx.token) {
+            errors.push("INFLUX_DB_TOKEN is required for core/enterprise");
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(`Configuration validation failed:\n${errors.join("\n")}`);
+    }
+}

package/build/helpers/enums/influx-product-types.enum.js

@@ -0,0 +1,8 @@
+export var InfluxProductType;
+(function (InfluxProductType) {
+    InfluxProductType["Core"] = "core";
+    InfluxProductType["Enterprise"] = "enterprise";
+    InfluxProductType["CloudDedicated"] = "cloud-dedicated";
+    InfluxProductType["CloudServerless"] = "cloud-serverless";
+    InfluxProductType["Clustered"] = "clustered";
+})(InfluxProductType || (InfluxProductType = {}));

package/build/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Standalone InfluxDB MCP Server
+ *
+ * Main entry point for the MCP server that provides InfluxDB integration
+ * for Claude Desktop and other MCP clients.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server/index.js";
+async function main() {
+    try {
+        const server = createServer();
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        console.error("[MCP] InfluxDB MCP Server started successfully");
+    }
+    catch (error) {
+        console.error("[MCP] Failed to start server:", error);
+        process.exit(1);
+    }
+}
+process.on("SIGINT", async () => {
+    console.error("[MCP] Shutting down...");
+    process.exit(0);
+});
+process.on("SIGTERM", async () => {
+    console.error("[MCP] Shutting down...");
+    process.exit(0);
+});
+main().catch((error) => {
+    console.error("[MCP] Server error:", error);
+    process.exit(1);
+});

package/build/prompts/index.js

@@ -0,0 +1,98 @@
+/**
+ * MCP Prompts Definitions
+ *
+ * Defines reusable prompt templates for InfluxDB operations
+ */
+/**
+ * Create simple MCP prompts for InfluxDB operations
+ */
+export function createPrompts(influxService) {
+    return [
+        {
+            name: "list-databases",
+            description: "Generate a prompt to list all available databases",
+            handler: async () => {
+                return {
+                    description: "List all available InfluxDB databases",
+                    messages: [
+                        {
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: "Please list all available databases in this InfluxDB instance. Use the list_databases tool to show me what databases are available.",
+                            },
+                        },
+                    ],
+                };
+            },
+        },
+        {
+            name: "check-health",
+            description: "Generate a prompt to check InfluxDB health status",
+            handler: async () => {
+                return {
+                    description: "Check InfluxDB server health and connection status",
+                    messages: [
+                        {
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: "Please check the health status of the InfluxDB server. Use the health_check tool to verify the connection and show me the server status.",
+                            },
+                        },
+                    ],
+                };
+            },
+        },
+        {
+            name: "load-context",
+            description: "Load custom database context and documentation",
+            handler: async () => {
+                const contextFile = await influxService.contextFile.loadContextFile();
+                if (!contextFile) {
+                    return {
+                        description: "No context file found",
+                        messages: [
+                            {
+                                role: "user",
+                                content: {
+                                    type: "text",
+                                    text: "No context file was found. Create a file in /context/ folder or name a file with 'context' in the name (.json, .txt, .md) to provide custom database documentation.",
+                                },
+                            },
+                        ],
+                    };
+                }
+                let mimeType = "text/plain";
+                switch (contextFile.extension) {
+                    case "json":
+                        mimeType = "application/json";
+                        break;
+                    case "md":
+                        mimeType = "text/markdown";
+                        break;
+                    case "txt":
+                    default:
+                        mimeType = "text/plain";
+                        break;
+                }
+                return {
+                    description: `Load context from ${contextFile.name}.${contextFile.extension}`,
+                    messages: [
+                        {
+                            role: "user",
+                            content: {
+                                type: "resource",
+                                resource: {
+                                    uri: "influx://context",
+                                    mimeType: mimeType,
+                                    text: contextFile.content,
+                                },
+                            },
+                        },
+                    ],
+                };
+            },
+        },
+    ];
+}