Bridging the Gap: InfluxDB as a Model Context Protocol (MCP) Server

This document details the implementation of an InfluxDB MCP server, enabling seamless integration between Large Language Models (LLMs) and time-series data stored within InfluxDB. By leveraging the InfluxDB OSS API v2, this server provides a standardized interface for LLMs to access, query, and manipulate data, fostering a new era of AI-driven time-series analysis and automation.

Core Capabilities

This MCP server unlocks the following key functionalities:

• Data Discovery: Exposes InfluxDB organizations, buckets, and measurements as addressable resources.
• Data Manipulation: Provides tools for writing data in line protocol format and executing complex Flux queries.
• Database Management: Enables the creation and management of database objects like buckets and organizations.
• Contextual Guidance: Offers prompt templates for common Flux queries and line protocol formatting, aiding LLM interaction.

Resource Endpoints

The server exposes the following resources via the influxdb:// protocol:

1. Organizations Listing: influxdb://orgs - Retrieves a list of all organizations within the InfluxDB instance. This allows LLMs to understand the organizational structure of the data.

2. Buckets Listing: influxdb://buckets - Returns a list of all buckets, including their associated metadata. This provides LLMs with information about available data storage locations.

3. Bucket Measurements: influxdb://bucket/{bucketName}/measurements - Lists all measurements within a specified bucket. This allows LLMs to discover the available data series within a given bucket.

4. Query Execution: influxdb://query/{orgName}/{fluxQuery} - Executes a provided Flux query against the InfluxDB instance and returns the results as a resource. This enables LLMs to perform complex data analysis and retrieval.

Toolset

The server provides the following tools for interacting with InfluxDB:

1. write-data: Writes time-series data to InfluxDB in line protocol format.

   • Parameters: org (organization name), bucket (bucket name), data (line protocol data), precision (optional: data precision).
   • Use Case: Enables LLMs to ingest data into InfluxDB based on insights or predictions.

2. query-data: Executes arbitrary Flux queries against InfluxDB.

   • Parameters: org (organization name), query (Flux query string).
   • Use Case: Allows LLMs to perform complex data analysis and retrieve specific information.

3. create-bucket: Creates a new bucket within InfluxDB.

   • Parameters: name (bucket name), orgID (organization ID), retentionPeriodSeconds (optional: retention period in seconds).
   • Use Case: Enables LLMs to dynamically create storage locations for new data streams.

4. create-org: Creates a new organization within InfluxDB.

   • Parameters: name (organization name), description (optional: organization description).
   • Use Case: Allows LLMs to manage the organizational structure of the InfluxDB instance.

Prompt Engineering

The server includes prompt templates to guide LLM interaction:

1. flux-query-examples: Provides examples of common Flux queries for various time-series analysis tasks. This helps LLMs understand the syntax and capabilities of Flux.

2. line-protocol-guide: Offers a comprehensive guide to the InfluxDB line protocol format. This enables LLMs to correctly format data for ingestion into InfluxDB.

Configuration and Deployment

The server requires the following environment variables:

• INFLUXDB_TOKEN (required): Authentication token for the InfluxDB API. Security Note: Store this token securely and avoid hardcoding it directly in your code.
• INFLUXDB_URL (optional): URL of the InfluxDB instance (defaults to http://localhost:8086).
• INFLUXDB_ORG (optional): Default organization name for certain operations.

Installation Options:

1. npx (Recommended): Run the server directly without installation.

   INFLUXDB_TOKEN=your_token npx influxdb-mcp-server

2. Global Installation: Install the server globally using npm.

   npm install -g influxdb-mcp-server
   INFLUXDB_TOKEN=your_token influxdb-mcp-server

3. From Source: Clone the repository and run the server locally.

   git clone https://github.com/idoru/influxdb-mcp-server.git
   cd influxdb-mcp-server
   npm install
   INFLUXDB_TOKEN=your_token npm start

Integration with Claude for Desktop:

Configure the server within your claude_desktop_config.json file.

Using npx:

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

Local Installation:

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

Architectural Overview

The server employs a modular architecture for enhanced maintainability and scalability:

• src/: Root directory containing the server's source code.
  • index.js: Main entry point for the server application.
  • config/: Configuration-related files.
    • env.js: Handles environment variable loading and validation.
  • utils/: Utility functions and modules.
    • influxClient.js: Provides a wrapper around the InfluxDB API client. This module should handle authentication and error handling.
    • loggerConfig.js: Configures the console logger for consistent logging across the application.
  • handlers/: Contains handlers for resource endpoints and tools.
    • organizationsHandler.js: Handles requests for listing organizations.
    • bucketsHandler.js: Handles requests for listing buckets.
    • measurementsHandler.js: Handles requests for listing measurements within a bucket.
    • queryHandler.js: Handles the execution of Flux queries.
    • writeDataTool.js: Implements the write-data tool.
    • queryDataTool.js: Implements the query-data tool.
    • createBucketTool.js: Implements the create-bucket tool.
    • createOrgTool.js: Implements the create-org tool.
  • prompts/: Stores prompt templates.
    • fluxQueryExamplesPrompt.js: Contains examples of Flux queries.
    • lineProtocolGuidePrompt.js: Provides a guide to the InfluxDB line protocol.

Testing Strategy

The repository includes integration tests to ensure the server's functionality:

• The tests spin up a Docker container with InfluxDB.
• Sample data is populated into the InfluxDB instance.
• All MCP server functionalities are tested against the populated data.

Running Tests:

npm test

These tests are crucial for verifying the correctness and stability of the server. Consider adding unit tests for individual modules to improve test coverage and isolate potential issues.

Conclusion

This InfluxDB MCP server provides a powerful bridge between LLMs and time-series data, enabling a wide range of AI-driven applications. By providing a standardized interface for data access, manipulation, and management, this server empowers developers to build intelligent systems that can analyze, predict, and automate tasks based on time-series data stored in InfluxDB. Future enhancements could include support for more advanced InfluxDB features, such as tasks and alerts, further expanding the capabilities of LLMs in the time-series domain.