⚠️ WARNING: Experimental project

This project is very unstable and subject to breaking changes. Do NOT use in production.

• Target: InfluxDB v1.x only. For new work, we strongly recommend InfluxDB v3 and official tooling.

• No stability or data-safety guarantees. Use at your own risk.

• APIs, tool names, and behavior may change without notice.

• Limited test coverage; issues are expected.

• If you must try it, run against disposable data and a non-critical environment.

• The code and information in this repository may be inaccurate and may not work as intended.

InfluxDB-v1-MCP: The MCP Server for InfluxDB v1.x

InfluxDB-v1-MCP is a powerful Model Context Protocol (MCP) interface specifically designed for InfluxDB v1.x, enabling AI assistants to intelligently manage and query time-series databases. Going beyond simple data retrieval, this server provides a complete toolkit that allows an AI agent to autonomously explore the database structure, understand data schemas, and execute complex InfluxQL queries.

Table of Contents

• Overview

• Core Components

• Available Tools

• Embeddings & Vector Store

• Configuration & Environment Variables

• Installation & Setup

• Usage Examples

• Integration - Claude desktop/Cursor/Windsurf

• Logging

• Testing

Overview

The InfluxDB MCP Server exposes a set of tools for interacting with InfluxDB time-series databases via a standardized protocol. It supports:

• Listing all accessible databases

• Listing all measurements (the equivalent of tables) in a specified database

• Creating new databases

• Retrieving measurement schemas (including fields and tags) to understand data structure

• Executing safe, read-only InfluxQL queries (SELECT, SHOW)

Core Components

• server.py: Main MCP server logic and tool definitions.

• config.py: Loads configuration from environment and .env files.

• tests/: Manual and automated test documentation and scripts.

Available Tools

Standard Database Tools

• list_databases

  • Lists all accessible databases.

  • Parameters: None

  • Example

    {
      "tool_name": "list_databases"
    }

• list_measurements

  • Lists all measurements (the equivalent of tables) in a specified database.

  • Parameters: database_name (string, required)

  • Example

    {
      "tool_name": "list_measurements",
      "parameters": {
        "database_name": "telegraf"
      }
    }

• get_measurement_schema

  • Retrieves the schema for a measurement (fields, tags, and their types).

  • Parameters: database_name (string, required), measurement_name (string, required)

  • Example

    {
      "tool_name": "get_measurement_schema",
      "parameters": {
        "database_name": "telegraf",
        "measurement_name": "cpu"
      }
    }

• execute_influxql

  • Executes a read-only InfluxQL query (SELECT, SHOW).

  • Parameters: influxql_query (string, required), database_name (string, optional)

  • Example

    {
      "tool_name": "execute_influxql",
      "parameters": {
        "database_name": "telegraf",
        "influxql_query": "SELECT \"usage_user\" FROM \"cpu\" WHERE time > now() - 1h"
      }
    }

• get_last_data_point_timestamp

  • Retrieves the timestamp of the most recent data point in a given measurement.

  • Parameters: database_name (string, required), measurement_name (string, required)

  • Example

    {
      "tool_name": "get_last_data_point_timestamp",
      "parameters": {
        "database_name": "telegraf",
        "measurement_name": "cpu"
      }
    }

• get_tag_values

  • Retrieves a list of all unique values for a specific tag key within a measurement.

  • Parameters: database_name (string, required), measurement_name (string, required), tag_key (string, required)

  • Example

    {
      "tool_name": "get_tag_values",
      "parameters": {
        "database_name": "telegraf",
        "measurement_name": "cpu",
        "tag_key": "cpu"
      }
    }

• get_time_window_summary

  • Calculates summary statistics (mean, max, min, 95th percentile) for a field over a specified time window.

  • Parameters: database_name (string, required), measurement_name (string, required), field_key (string, required), time_window (string, required), filters (string, optional), group_by_tags (string, optional)

  • Example

    {
      "tool_name": "get_time_window_summary",
      "parameters": {
        "database_name": "telegraf",
        "measurement_name": "cpu",
        "field_key": "usage_user",
        "time_window": "1h",
        "group_by_tags": "cpu"
      }
    }

Configuration & Environment Variables

All configuration is via environment variables (typically set in a .env file):

Example .env file

INFLUXDB_URL=http://localhost:8086
INFLUXDB_USER=your_db_user
INFLUXDB_PASSWORD=your_db_password

Installation & Setup

Requirements

• Python 3.11 (see .python-version)

• uv (dependency manager; install instructions)

• MariaDB server (local or remote)

Steps

1. Clone the repository

2. Install uv (if not already):

   pip install uv

3. Install dependencies

   uv pip compile pyproject.toml -o uv.lock

   uv pip sync uv.lock

4. Create .env in the project root (see Configuration)

5. Run the server

   python server.py

   Adjust entry point if needed (e.g., main.py)

Integration - Claude desktop/Cursor/Windsurf/VSCode

{
  "mcpServers": {
    "influxdb-v1": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/server/directory/",
        "run",
        "server.py"
        ],
        "envFile": "path/to/mcp-server-mariadb-vector/.env"      
    }
  }
}

or If already running MCP server

{
  "servers": {
    "influxdb-v1": {
      "url": "http://{host}:9003/sse",
      "type": "sse"
    }
  }
}

Logging

• Logs are written to logs/mcp_server.log by default.

• Log messages include tool calls, configuration issues, embedding errors, and client requests.

• Log level and output can be adjusted in the code (see config.py and logger setup).