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: v20.11 or newer (for npm/npx usage)
• pnpm: use the version pinned in package.json for local development. Run corepack enable to activate it with Node.js 20 or 22.
• Docker: (for Docker-based setup)

---

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

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	Deprecated since 2.0.0. Use query_sql. Retained for compatibility	All versions
query_sql	Run bounded read-only SQL with structured response metadata	All versions
query_influxql	Run bounded read-only InfluxQL with structured response metadata	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
list_tables	List tables, also called measurements, in a database	All versions
describe_table	Describe table schema with conservative column categories	All versions
investigate_database	Run high-level read-only database discovery and sampling	All versions
create_admin_token	Create a named admin token with an optional expiration	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	Enterprise only
list_resource_tokens	List all resource tokens (with filtering and ordering)	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:

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:

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

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

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

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

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

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

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.

Optional MCP tool profile and telemetry

Use INFLUX_MCP_TOOL_PROFILE=readonly to expose only read-only tools. If unset, the server uses the full operator tool profile.

INFLUX_MCP_TOOL_PROFILE=readonly

Tool-call telemetry is enabled by default and writes structured JSON lines to stderr, which keeps stdout reserved for MCP stdio protocol messages. To disable telemetry:

MCP_LOG_TOOL_CALLS=false

To write telemetry to a file, configure the file backend:

MCP_LOG_BACKEND=file
MCP_LOG_FILE=/logs/influxdb-mcp.jsonl

The telemetry log includes tool name, request ID, query ID, duration, database, row count, truncation state, success state, and error code. It does not log API tokens, request headers, tool arguments, or query text. Sample harness profiles live in harness-profiles/; for approval settings and repeatable E2E prompts, see AGENT_E2E_TESTS.md.

---

2. Integration with MCP Clients

A. Local (pnpm install & run)

1. Install dependencies:

   pnpm install
   

2. Build the server:

   pnpm run build
   

3. Configure your MCP client to use the built server. Example (see example-local.mcp.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):

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

# Option 1: Use docker compose (recommended)
docker compose build
# Option 2: Use pnpm script
pnpm run docker:build

a) Docker with remote InfluxDB instance (see example-docker.mcp.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:

{
  "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.
• See AGENT_E2E_TESTS.md for MCP harness tips, read-only profile runs, and telemetry correlation checks.

Run Cloud Serverless integration tests

The Cloud Serverless test command accepts Claire's INFLUXDB3_CLOUD_* variables and maps them to the MCP server's runtime variables. The command sets INFLUX_TEST_ENABLED=true and INFLUX_DB_PRODUCT_TYPE=cloud-serverless.

For local tests with 1Password, store only op:// references in ~/.config/claire/cloud-serverless.env:

INFLUXDB3_CLOUD_URL=op://VAULT/ITEM/hostname
INFLUXDB3_CLOUD_TOKEN=op://VAULT/ITEM/token
INFLUXDB3_CLOUD_BUCKET=op://VAULT/ITEM/bucket
INFLUXDB3_CLOUD_ORG=op://VAULT/ITEM/org

Run the live tests through 1Password so the token exists only in the test process environment:

op run --env-file ~/.config/claire/cloud-serverless.env -- \
  pnpm run test:integration:cloud-serverless

You can instead copy env.cloud-serverless.example to the ignored .env.cloud-serverless.local file and set the MCP runtime variables there. Then run pnpm run test:integration:cloud-serverless directly.

To use another plaintext credentials file, set INFLUX_TEST_ENV_FILE:

INFLUX_TEST_ENV_FILE=/path/to/serverless.env pnpm run test:integration:cloud-serverless

GitHub Actions runs the same command with the existing URL and token secrets from the cloud-serverless environment. The workflow selects the mcp-ci-tests bucket explicitly.

Database Retention Policy Examples

Core/Enterprise - Set 90-day Retention

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

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

Write errors

write_line_protocol surfaces InfluxDB's own error text, not a generic message. If InfluxDB rejects a write — a duplicate tag key, an unauthenticated token, a payload over the size limit — the tool error includes the specific reason, for example:

Bad request: invalid line protocol - multiple instances of 'region' tag found

A 503 reaching this server is phrased as retryable (Service temporarily unavailable, retry the write: ...) — safe to retry the write. Any other status is not.

InfluxDB 3.11 compatibility

Verified against InfluxDB 3.11.5 Core and Enterprise, including a multi-node Enterprise cluster). Core and Enterprise write through POST /api/v3/write_lp, which 3.11's write-availability changes for the legacy /api/v2/write endpoint do not affect; only clustered calls /api/v2/write. Query and schema-discovery tools behave the same whether the target database is on Parquet (Core, or Enterprise before an upgrade) or PachaTree (Enterprise 3.11+ by default, or after --upgrade-pacha-tree) — new system.pt_* tables are excluded from get_measurements/get_measurement_schema results by the same table_schema = 'iox' filter that already excludes other system tables.

Core and Enterprise create named admin tokens through POST /api/v3/configure/token/named_admin. Named admin tokens accept an optional expiration in seconds. Only Enterprise supports resource tokens, so the MCP server doesn't advertise resource-token tools for Core connections.

---

Publishing to the MCP Registry

Stable GitHub releases publish the npm package first, then register io.github.influxdata/influxdb3-mcp-server in the official MCP Registry. The registry stores metadata; clients install the server from npm. GitHub OIDC authenticates the release job using id-token: write, so no additional registry secret is needed. Releases marked as prereleases or with - in their tag skip registry publishing.

Before tagging a release, update package.json, src/config.ts, the latest CHANGELOG.md entry, and both version fields in server.json together. Keep package.json's mcpName equal to server.json's name. Check locally:

node scripts/check-versions.js
bash scripts/install-mcp-publisher.sh /tmp/mcp-publisher
/tmp/mcp-publisher validate

The installer pins and verifies the Linux amd64 publisher used in CI. The validate command contacts the registry and checks metadata without publishing. CI runs these checks, and the npm release job also checks the versions and tag. The first registry release must use a freshly published npm version containing mcpName; an existing npm version cannot be updated to add it.

After publishing, verify the release at each destination:

• npm: The exact package version must exist and include the expected mcpName.
• Docker Hub: The image tagged with the release version must be available.
• MCP Registry: The exact version endpoint must return the expected server name and version. The registry release job automates this check.

From the release checkout, verify npm and the registry manually:

version="$(node -p "require('./package.json').version")"
pnpm view "@influxdata/influxdb3-mcp-server@$version" version mcpName
docker manifest inspect "influxdata/influxdb3-mcp-server:$version"
curl --fail --silent --show-error \
  "https://registry.modelcontextprotocol.io/v0.1/servers/io.github.influxdata%2Finfluxdb3-mcp-server/versions/$version" \
  | jq --exit-status --arg version "$version" \
    '.server.name == "io.github.influxdata/influxdb3-mcp-server" and .server.version == $version'

With valid database environment variables configured, also smoke-test the exact published npm version using MCP Inspector:

npx @modelcontextprotocol/inspector --cli \
  npx -y "@influxdata/influxdb3-mcp-server@$version" --method tools/list

Metadata validation checks the registry description; the smoke test checks that the published package initializes and advertises tools. Keep the release-note verification checklist unchecked until the corresponding checks pass.

If registry publishing fails after npm succeeds, rerun only the failed registry job; rerunning the successful npm job would try to publish an existing version.

License

MIT