InfluxDB 3

InfluxDB 3 MCP Server

用于集成 InfluxDB 3 的 Model Context Protocol（MCP）服务。通过 MCP 客户端提供工具、资源和提示词，以便与 InfluxDB 3 Core 和 Enterprise，以及 InfluxDB Cloud Dedicated、InfluxDB Clustered 和 InfluxDB Cloud Serverless 交互。

---

前置条件

• InfluxDB 3 实例：URL 和令牌（Core/Enterprise/Cloud Serverless），或集群 ID 和令牌（Cloud Dedicated/Clustered）
• Node.js：v20.11 或更高版本（用于 npm/npx）
• pnpm：本地开发时使用 package.json 中指定的版本。 运行 corepack enable，通过 Node.js 20 或 22 启用它。
• Docker：（用于基于 Docker 的设置）

---

迁移到 2.0

2.0 版本更改了查询结果封装、健康检查输出、参数错误 和遥测。解析这些响应的客户端必须遵循 只读输出契约。 将查询结果视为完整答案前，请先读取 metadata.completeness、上限和警告。 发现元数据会注明其来源，并将不可用的值保留为未知。 工具名称和已配置的配置文件仍然可用。

只读 Agent 工作流

设置 INFLUX_MCP_TOOL_PROFILE=readonly，即可为 MCP 客户端提供用于探索 和查询数据的工具。此配置文件不包含任何写入数据、管理数据库、管理令牌 或在主机上运行的工具。

凭据

将 INFLUX_DB_TOKEN 设置为管理员令牌、范围受限的令牌或 Enterprise 用户身份验证 JWT。服务会在 Bearer 标头中发送该令牌，不会检查令牌内容， 因此令牌的权限决定了这些工具可以读取哪些数据库。

查询参数

query_sql 和 query_influxql 接受 database 作为 db 的别名，接受 query 作为 q 的别名。 如果一次调用同时提供这两种名称且值不同，则会返回 invalid_arguments 错误。所有参数错误都会作为结构化工具错误，并被记录在遥测中。

发现

list_databases 会返回服务列出的数据库，并将其标记为 visibility: "unknown"， 因为列出的数据库仍可能不可读。health_check 会返回包含独立健康状态和 ping 结果的 JSON。 范围受限的令牌可能被拒绝执行这两项检查，但仍能读取其数据库。

investigate_database 会保留每个表的结果，即使其他表发生错误， 并报告它看到的表数量以及是否提前停止。样本来自一个时间窗口，默认值为 24 小时； 设置 sampleWindowHours 可更改此值。时间窗口内没有数据并不意味着表是空的。 在 Core 和 Enterprise 上，describe_table 和调查功能使用 system.influxdb_schema 获取权威列角色信息。 如果相同凭据允许访问，它们还会从 _internal 目录读取模式和删除状态， 并报告 source: "server" 和目录表名。不可用的值会保留为 unknown；目录访问被拒绝时， 不会丢弃可读取的列元数据或样本。 如果没有权威删除元数据，带有时间戳格式后缀的表名会收到一条建议性的 possibly_deleted 警告，并继续列出。当前尚不支持基数估算。

错误

调用失败时，请读取 error.code、error.recovery 和 error.retryable：

• 403 表示 not_found_or_denied。没有访问权限的令牌无论数据库是否存在，都会收到 403。
• 404 表示 not_found。
• 指定未知表名的 SQL 查询，其 recovery 为 "fix_reference"。 请调用 list_tables 或 describe_table 查找正确的名称。
• 因服务器内存不足而无法完成的查询，其 recovery 为 "narrow"。
• 发送到 Enterprise 仅支持摄取数据的节点的查询，其 recovery 为 "change_endpoint"。
• 其他服务器故障的 recovery 为 "none"。

EXPLAIN ANALYZE 会在相同限制范围内运行查询，并添加 diagnostic_execution 警告。

分析师探索陌生数据库

分析师可以连接 Claude Desktop、Cursor、Codex 等 MCP 客户端，或 其他 Agent 执行环境，并提出类似以下的问题：

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

使用只读配置时，Agent 可以：

1. 调用 list_databases 查看可访问的数据库。
2. 调用 list_tables 和 describe_table，了解测量项和 列。
3. 将不确定的标签和字段类别视为 unknown。
4. 使用 db、q 和可选的 params 构建有界 SQL 查询。
5. 调用 query_sql，获取结构化 JSON 输出。
6. 返回结果、行数、截断状态、警告和关联元数据。

用户可以获得有依据的回答和可复用的查询，同时 Agent 能够探索 并查询数据，而无法访问变更或管理工具。

操作员调查 InfluxQL 仪表板查询

操作员可以排查现有的 InfluxQL 仪表板面板，并提出：

Why did this panel stop showing data after the deploy?

使用只读配置时，Agent 可以：

1. 保留用户的 InfluxQL 查询，并调用 query_influxql。
2. 使用 SHOW 查询和架构发现，核实测量项及其引用的 列。
3. 通过有界读取抽样近期行，以区分数据缺失和查询故障。
4. 拒绝不安全的后续操作，例如 SELECT INTO 或破坏性语句。
5. 返回 request_id、query_id 和 query_id_source，以便操作员在 查询历史记录可用时，将 MCP 结果与 system.queries.id 关联起来。
6. 对 stdio 传输输出结构化日志到 stderr，使 stdout 保留 给 MCP 协议消息使用。

用户可以获得实用的诊断结果，例如数据缺失、架构已重命名、时间条件 错误或查询失败。调查过程可追踪，且默认不会记录完整查询文本。

---

可用工具

工具名称	描述	可用性
load_database_context	加载可选的自定义数据库上下文和文档	所有版本
get_help	获取 InfluxDB 操作的帮助和故障排除指南	所有版本
write_line_protocol	使用 InfluxDB 行协议写入数据	所有版本
create_database	创建新数据库（支持特定于云的配置选项）	所有版本
update_database	更新数据库配置（所有版本均支持保留策略；Cloud Dedicated/Clustered 支持 maxTables/maxColumns）	所有版本
delete_database	按名称删除数据库（不可逆）	所有版本
execute_query	自 2.0.0 起已弃用。请使用 query_sql。保留以确保兼容性	所有版本
query_sql	执行有界的只读 SQL 查询，并返回结构化响应元数据	所有版本
query_influxql	执行有界的只读 InfluxQL 查询，并返回结构化响应元数据	所有版本
get_measurements	列出数据库中的所有测量（表）	所有版本
get_measurement_schema	获取测量/表的架构（列/类型）	所有版本
list_tables	列出数据库中的表（也称为测量）	所有版本
describe_table	描述表架构，并保守地分类列	所有版本
investigate_database	执行高层级的只读数据库发现和采样	所有版本
create_admin_token	创建具有可选过期时间的命名管理员令牌	仅 Core/Enterprise
list_admin_tokens	列出所有管理员令牌（可选筛选）	仅 Core/Enterprise
create_resource_token	为特定数据库和权限创建资源令牌	仅 Enterprise
list_resource_tokens	列出所有资源令牌（支持筛选和排序）	仅 Enterprise
delete_token	按名称删除令牌	仅 Core/Enterprise
regenerate_operator_token	重新生成操作员令牌（危险/不可逆）	仅 Core/Enterprise
cloud_list_database_tokens	列出 Cloud-Dedicated/Clustered 集群的所有数据库令牌	Cloud Dedicated/Clustered
cloud_get_database_token	按 ID 获取特定数据库令牌的详细信息	Cloud Dedicated/Clustered
cloud_create_database_token	为 Cloud-Dedicated/Clustered 集群创建新的数据库令牌	Cloud Dedicated/Clustered
cloud_update_database_token	更新现有数据库令牌	Cloud Dedicated/Clustered
cloud_delete_database_token	从 Cloud-Dedicated/Clustered 集群中删除数据库令牌	Cloud Dedicated/Clustered
list_databases	列出实例中所有可用的数据库	所有版本
health_check	检查 InfluxDB 连接和运行状况	所有版本

---

可用资源

资源名称	描述
influx-config	对 InfluxDB 配置的只读访问权限
influx-status	实时连接和运行状况
influx-databases	实例中所有数据库的列表
context-file	用户自定义的数据库上下文和文档

---

可用提示词

提示词名称	描述
list-databases	生成用于列出所有可用数据库的提示词
check-health	生成用于检查 InfluxDB 运行状况的提示词
load-context	加载自定义数据库上下文和文档

---

设置与集成指南

1. 环境变量

对于 Core/Enterprise InfluxDB：

必须提供：

• INFLUX_DB_INSTANCE_URL（例如 http://localhost:8181/）
• INFLUX_DB_TOKEN
• INFLUX_DB_PRODUCT_TYPE（core 或 enterprise）

.env 示例：

INFLUX_DB_INSTANCE_URL=http://localhost:8181/
INFLUX_DB_TOKEN=your_influxdb_token_here
INFLUX_DB_PRODUCT_TYPE=core

对于 Cloud Serverless InfluxDB：

必须提供：

• INFLUX_DB_INSTANCE_URL（例如 https://us-east-1-1.aws.cloud2.influxdata.com）
• INFLUX_DB_TOKEN
• INFLUX_DB_PRODUCT_TYPE（cloud-serverless）

.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

对于 Cloud Dedicated InfluxDB：

必须提供 INFLUX_DB_PRODUCT_TYPE=cloud-dedicated 和 INFLUX_DB_CLUSTER_ID，以及以下令牌组合之一：

选项 1：仅数据库令牌（仅限查询/写入操作）：

INFLUX_DB_PRODUCT_TYPE=cloud-dedicated
INFLUX_DB_CLUSTER_ID=your_cluster_id_here
INFLUX_DB_TOKEN=your_database_token_here

选项 2：仅管理令牌（仅限数据库管理）：

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

选项 3：两个令牌（完整功能）：

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

对于 Clustered InfluxDB：

必须提供 INFLUX_DB_PRODUCT_TYPE=clustered 和 INFLUX_DB_INSTANCE_URL，以及以下令牌组合之一：

选项 1：仅数据库令牌（仅限查询/写入操作）：

INFLUX_DB_PRODUCT_TYPE=clustered
INFLUX_DB_INSTANCE_URL=https://your_cluster_host.com
INFLUX_DB_TOKEN=your_database_token_here

选项 2：仅管理令牌（仅限数据库管理）：

INFLUX_DB_PRODUCT_TYPE=clustered
INFLUX_DB_INSTANCE_URL=https://your_cluster_host.com
INFLUX_DB_MANAGEMENT_TOKEN=your_management_token_here

选项 3：两个令牌（完整功能）：

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

示例和详细信息请参阅相应的 env.<instancetype>.example。

可选的 MCP 工具配置文件和遥测

使用 INFLUX_MCP_TOOL_PROFILE=readonly 仅公开只读工具。若未设置，服务将使用完整的运维工具配置文件。

INFLUX_MCP_TOOL_PROFILE=readonly

工具调用遥测默认启用，并会将结构化 JSON 行写入 stderr，同时将 stdout 保留给 MCP stdio 协议消息。若要 禁用遥测：

MCP_LOG_TOOL_CALLS=false

若要将遥测写入文件，请配置文件后端：

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

遥测日志包含工具名称、请求 ID、查询 ID、耗时、数据库、 行数、截断状态、成功状态和错误代码。不会记录 API 令牌、请求标头、工具参数或查询文本。示例测试框架配置文件位于 harness-profiles/；有关审批设置和可重复的 E2E 提示词， 请参阅 AGENT_E2E_TESTS.md。

---

2. 与 MCP 客户端集成

A. 本地（pnpm 安装并运行）

1. 安装依赖项：

   pnpm install
   

2. 构建服务：

   pnpm run build
   

3. **将 MCP 客户端配置为使用构建好的服务。**示例（参见 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. 本地（使用 npx，无需安装/构建）

1. 直接使用 npx 运行（发布到 npm 后即可，目前尚不可用）：

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

运行 Docker 集成前，必须构建 Docker 镜像：

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

a）使用远程 InfluxDB 实例的 Docker（参见 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 中运行 InfluxDB（参见 example-docker.mcp.json）：

将 host.docker.internal 用作 InfluxDB URL，以便 MCP 服务容器能够访问 InfluxDB 容器：

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

---

示例用法

• 使用 MCP 客户端调用上述工具、资源或提示词。
• 自定义上下文：编辑提供的 context/database-context.md 文件，或移除该文件并创建一个文件名中包含“context”的自定义上下文文件（.json、.txt、.md），以提供数据库文档。使用 load_database_context 工具或 load-context 提示词访问该文件。
• 查看 example-*.mcp.json 文件，获取可直接使用的配置模板：
  • example-local.mcp.json - 本地开发设置
  • example-npx.mcp.json - 基于 NPX 的设置
  • example-docker.mcp.json - 基于 Docker 的设置
  • example-cloud-dedicated.mcp.json - 包含所有变量的 Cloud Dedicated
  • example-clustered.mcp.json - 包含所有变量的 Clustered
  • example-cloud-serverless.mcp.json - Cloud Serverless 配置
• 查看 env.example、env.cloud-dedicated.example、env.clustered.example 和 env.cloud-serverless.example 文件，获取环境变量模板。
• 查看 AGENT_E2E_TESTS.md，了解 MCP 测试框架的提示、只读配置运行方式和遥测关联检查。

运行 Cloud Serverless 集成测试

Cloud Serverless 测试命令接受 Claire 的 INFLUXDB3_CLOUD_* 变量， 并将它们映射到 MCP 服务的运行时变量。 该命令会设置 INFLUX_TEST_ENABLED=true 和 INFLUX_DB_PRODUCT_TYPE=cloud-serverless。

使用 1Password 运行本地测试时，只需在 ~/.config/claire/cloud-serverless.env 中存储 op:// 引用：

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

通过 1Password 运行实时测试，这样令牌就只会存在于测试 进程的环境中：

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

你也可以将 env.cloud-serverless.example 复制到被忽略的 .env.cloud-serverless.local 文件中，并在那里设置 MCP 运行时变量。 然后直接运行 pnpm run test:integration:cloud-serverless。

若要使用其他明文凭据文件，请设置 INFLUX_TEST_ENV_FILE：

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

GitHub Actions 使用 cloud-serverless 环境中的现有 URL 和令牌密钥 运行同一命令。工作流会显式选择 mcp-ci-tests 存储桶。

数据库保留策略示例

Core/Enterprise - 设置 90 天保留期限

// Set 90-day retention policy on Enterprise instance
await mcp.update_database({
  name: "my_database",
  retentionPeriod: 7776000000000000, // 90 days in nanoseconds
});

Cloud Dedicated - 更新多项设置

// Update retention, maxTables, and maxColumnsPerTable
await mcp.update_database({
  name: "my_database",
  retentionPeriod: 7776000000000000, // 90 days
  maxTables: 1000,
  maxColumnsPerTable: 250,
});

常见保留期限

时长	纳秒
7 天	604,800,000,000,000
30 天	2,592,000,000,000,000
90 天	7,776,000,000,000,000
180 天	15,552,000,000,000,000
1 年	31,536,000,000,000,000

---

支持与故障排除

• 使用 get_help 工具获取内置帮助和故障排除信息。
• 如果遇到连接问题，请检查环境变量和 InfluxDB 实例状态。
• 有关高级配置，请参阅示例 .env 和 MCP 配置文件中的注释。

写入错误

write_line_protocol 会显示 InfluxDB 自身的错误文本，而不是通用 消息。如果 InfluxDB 拒绝写入——例如标签键重复、令牌未经身份验证， 或负载超过大小限制——工具错误会包含具体原因，例如：

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

到达此服务的 503 会表述为可重试错误 （Service temporarily unavailable, retry the write: ...）——可以安全地重试 写入。其他任何状态都不可重试。

InfluxDB 3.11 兼容性

已针对 InfluxDB 3.11.5 Core 和 Enterprise 验证，包括多节点 Enterprise 集群。Core 和 Enterprise 通过 POST /api/v3/write_lp 写入；3.11 对旧版 /api/v2/write 端点所做的写入可用性变更不会影响这一行为；只有 clustered 会调用 /api/v2/write。无论目标数据库使用 Parquet（Core，或升级前的 Enterprise）还是 PachaTree（默认用于 Enterprise 3.11+，或执行 --upgrade-pacha-tree 后），查询和架构发现工具的行为都相同——get_measurements/get_measurement_schema 结果会使用同一个 table_schema = 'iox' 过滤条件排除新的 system.pt_* 表；该过滤条件也会排除其他系统表。

Core 和 Enterprise 均通过 POST /api/v3/configure/token/named_admin 创建命名管理员令牌。 命名管理员令牌可选设置以秒为单位的过期时间。 只有 Enterprise 支持资源令牌，因此 MCP 服务不会为 Core 连接公布资源令牌工具。

---

发布到 MCP 注册表

稳定版 GitHub 发布会先发布 npm 包，然后在官方 MCP 注册表注册 io.github.influxdata/influxdb3-mcp-server。 注册表存储元数据；客户端从 npm 安装服务。 GitHub OIDC 使用 id-token: write 对发布任务进行身份验证，因此无需额外的注册表密钥。标记为预发布版本或标签中包含 - 的发布会跳过注册表发布。

标记发布版本前，请同时更新 package.json、src/config.ts、最新的 CHANGELOG.md 条目，以及 server.json 中的两个 version 字段。 确保 package.json 的 mcpName 与 server.json 的 name 一致。在本地检查：

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

安装程序会固定并验证 CI 中使用的 Linux amd64 发布工具。validate 命令会联系注册表并检查元数据，但不会发布。 CI 会运行这些检查，npm 发布任务也会检查版本和标签。 首次发布到注册表时，必须使用包含 mcpName 的新发布 npm 版本；现有 npm 版本无法更新以添加该字段。

发布后，请在每个目标位置验证发布内容：

• npm： 必须存在确切的软件包版本，并且其中包含预期的 mcpName。
• Docker Hub： 必须能获取带有该发布版本标签的镜像。
• MCP 注册表： 确切版本的端点必须返回预期的服务名称和版本。注册表发布任务会自动执行此检查。

在发布检出目录中，手动验证 npm 和注册表：

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'

配置好有效的数据库环境变量后，还要使用 MCP Inspector 对确切发布的 npm 版本进行冒烟测试：

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

元数据验证会检查注册表描述；冒烟测试会检查已发布的软件包是否能初始化并公布工具。对应检查通过前，请勿勾选发布说明中的验证清单项。

如果 npm 发布成功后注册表发布失败，只需重新运行失败的注册表任务；重新运行已成功的 npm 任务会尝试再次发布已存在的版本。

许可证

MIT