# InfluxDB 3 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 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](docs/read-only-output-contract.md).
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:

```text
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:

```text
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`:

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

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

```env
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:

```env
MCP_LOG_TOOL_CALLS=false
```

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

```env
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:**
   ```bash
   pnpm install
   ```
2. **Build the server:**
   ```bash
   pnpm 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 pnpm script
pnpm 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.
- 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`:

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

```bash
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`:

```bash
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

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

```typescript
// 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](https://modelcontextprotocol.io/registry/about).
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:

```sh
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:

```sh
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](https://modelcontextprotocol.io/docs/tools/inspector):

```sh
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](LICENSE)