InfluxDB 3

InfluxDB 3 MCP Server

Model Context Protocol (MCP) server for InfluxDB 3 integration. Provides tools, resources, and prompts for interacting with InfluxDB 3 Core and Enterprise, plus InfluxDB Cloud Dedicated, InfluxDB Clustered, and InfluxDB 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: 22.23.4 or a later 22.x, 24.22.1 or a later 24.x, or 26.12.1 or newer (for npm/npx usage)
• pnpm: use the version pinned in package.json for local development. Run corepack enable to activate it.
• Docker: (for Docker-based setup)

Node.js verifies TLS servers with a root certificate store built into the node binary. Earlier releases include roots that chain to compromised eMudhra/emSign intermediate CAs. The Docker image uses the latest Node.js 24 release. npm/npx installations use your local Node.js, so update it to a release listed above. Node.js 20 is end of life and has no fixed release.

Migrating to 2.0

Version 2.0 changes query result envelopes, health-check output, argument errors, and telemetry. Clients that parse these responses must follow the read-only output contract. Read metadata.completeness, caps, and warnings before treating query results as a complete answer. Discovery metadata states its source and leaves unavailable values unknown. Tool names and configured profiles remain available.

Read-only Agent Workflows

Set INFLUX_MCP_TOOL_PROFILE=readonly to give an MCP client tools that explore and query data. The profile leaves out every tool that writes data, administers databases, manages tokens, or runs on the host.

Credentials

Set INFLUX_DB_TOKEN to an admin token, a scoped token, or an Enterprise user-authentication JWT. The server sends it in a Bearer header without inspecting it, so the token's permissions decide which databases the tools can read.

Query arguments

query_sql and query_influxql accept database for db and query for q. A call that gives both names with different values fails with invalid_arguments. Every argument error is a structured tool error and is recorded in telemetry.

Discovery

list_databases returns what the server lists, with visibility: "unknown", because a listed database might still be unreadable. health_check returns JSON with separate health and ping outcomes. A scoped token can be denied both checks and still read its databases.

investigate_database keeps each table's result even when another table fails, and reports how many tables it saw and whether it stopped early. Samples come from a time window, 24 hours by default; set sampleWindowHours to change it. An empty window doesn't mean the table is empty. On Core and Enterprise, describe_table and investigation use system.influxdb_schema for authoritative column roles. They also read schema mode and deletion status from the _internal catalog when the same credential permits it, reporting source: "server" and the catalog table name. Unavailable values stay unknown; catalog denial does not discard readable column metadata or samples. Without authoritative deletion metadata, a table name with a timestamp-shaped suffix gets an advisory possibly_deleted warning and stays listed. Cardinality estimates aren't supported yet.

Errors

When a call fails, read error.code, error.recovery, and error.retryable:

• A 403 is not_found_or_denied. A token without access gets 403 whether or not the database exists.
• A 404 is not_found.
• A SQL query that names an unknown table has recovery: "fix_reference". Call list_tables or describe_table for the right name.
• A query that runs out of server memory has recovery: "narrow".
• A query sent to an Enterprise ingest-only node has recovery: "change_endpoint".
• Other server failures have recovery: "none".

EXPLAIN ANALYZE runs the query within the same bounds and adds a diagnostic_execution warning.

Analyst explores an unfamiliar database

An analyst can connect an MCP client such as Claude Desktop, Cursor, Codex, or another agent harness and ask a question like:

Which sensors had the highest average temperature in the last 24 hours?

With the read-only profile, the agent can:

1. Call list_databases to see accessible databases.
2. Call list_tables and describe_table to discover measurements and columns.
3. Treat uncertain tag and field categories as unknown.
4. Build a bounded SQL query with db, q, and optional params.
5. Call query_sql with structured JSON output.
6. Return the result, row count, truncation status, warnings, and correlation metadata.

The user gets a grounded answer and a reusable query while the agent explores and queries data without access to mutation or administration tools.

Operator investigates an InfluxQL dashboard query

An operator can troubleshoot an existing InfluxQL dashboard panel and ask:

Why did this panel stop showing data after the deploy?

With the read-only profile, the agent can:

1. Keep the user's query in InfluxQL and call query_influxql.
2. Use SHOW queries and schema discovery to verify the measurement and referenced columns.
3. Sample recent rows with bounded reads to distinguish missing data from a broken query.
4. Reject unsafe follow-up attempts, such as SELECT INTO or destructive statements.
5. Return request_id, query_id, and query_id_source so the operator can correlate the MCP result with system.queries.id when query history is available.
6. Emit structured logs to stderr for stdio transports so stdout remains reserved for MCP protocol messages.

The user gets a practical diagnosis, such as missing data, renamed schema, a wrong time predicate, or a query failure. The investigation is traceable without logging full query text by default.

Available Tools

Available Resources

| influx-databases | List of all databases in the instan