InfluxDB MCP Server

InfluxDB v2 MCP 服务

一个模型上下文协议（MCP）服务，通过 InfluxDB OSS API v2 提供对 InfluxDB v2 实例的访问。该服务主要使用 Claude Code 构建。

功能

此 MCP 服务提供：

• 资源：访问组织、存储桶和测量数据
• 工具：写入数据、执行查询和管理数据库对象
• 提示词：常见 Flux 查询和 Line Protocol 格式的模板

资源

此服务提供以下资源：

1. 组织列表：influxdb://orgs

   • 显示 InfluxDB 实例中的所有组织

2. 存储桶列表：influxdb://buckets

   • 显示所有存储桶及其元数据

3. 存储桶测量项：influxdb://bucket/{bucketName}/measurements

   • 列出指定存储桶中的所有测量项（使用 INFLUXDB_ORG）

4. 查询数据：influxdb://query/{orgName}/{fluxQuery}

   • 执行 Flux 查询并以 JSON 格式返回结果（包含 headers，以及所有结果表中每行对应的一条记录）

模板变量（bucketName、orgName、fluxQuery）必须进行百分比编码，例如使用 encodeURIComponent，以确保包含空格或 / 的名称和多行查询能够在 URI 中正确保留。

工具

此服务提供以下工具：

1. write-data：以行协议格式写入时序数据

   • 参数：org、bucket、data、precision（可选）
   • 设置了 INFLUXDB_ORG / INFLUXDB_BUCKET 时，org 和 bucket 为可选参数；未指定时将使用对应的环境变量值

2. query-data：执行 Flux 查询

   • 参数：org、query
   • 设置了 INFLUXDB_ORG 时，org 为可选参数；未指定时将使用该环境变量值

3. create-bucket：创建新的存储桶

   • 参数：name、orgID、retentionPeriodSeconds（可选，单位为整秒；省略或传入 0 表示永久保留）

4. create-org：创建新的组织

   • 参数：name、description（可选）

提示词

此服务提供以下提示词模板：

1. flux-query-examples：常见 Flux 查询示例
2. line-protocol-guide：InfluxDB 行协议格式指南

配置

服务器需要以下环境变量：

• INFLUXDB_TOKEN（必填）：InfluxDB API 的身份验证令牌
• INFLUXDB_URL（可选）：InfluxDB 实例的 URL（默认为 http://localhost:8086）
• INFLUXDB_ORG（可选）：某些操作的默认组织名称。设置后，write-data 和 query-data 工具中的 org 可省略
• INFLUXDB_BUCKET（可选）：默认存储桶名称。设置后，write-data 工具中的 bucket 可省略
• DEBUG（可选）：设置为 mcp:*，即可将每条 MCP 消息记录到 stderr。这包括查询文本和写入的数据，因此请勿在生产环境中启用

以下变量仅适用于 Streamable HTTP 传输（参见HTTP 传输安全）：

• MCP_HTTP_HOST（可选）：监听的接口（默认为 127.0.0.1；与 --host 相同）
• MCP_AUTH_TOKEN（可选）：设置后，每个请求都必须发送 Authorization: Bearer <token>。监听非回环接口时必填
• MCP_ALLOWED_HOSTS（可选）：以逗号分隔的主机名（忽略端口），用于指定 Host 标头中允许的主机名。默认为 localhost,127.0.0.1,[::1]，并包含回环地址上的绑定地址；在其他接口上未设置时，不检查 Host
• MCP_HTTP_ALLOW_UNAUTHENTICATED（可选）：设置为 true，即可在未设置 MCP_AUTH_TOKEN 的情况下监听非回环接口，例如在由反向代理代为进行身份验证时
• MCP_HTTP_BODY_LIMIT（可选）：请求正文大小上限（默认为 4mb；可使用 b、kb 或 mb 后缀）。对于非常大的 write-data 批次，请调高此值

向 InfluxDB 发送的请求会在 10 秒后超时（查询为 60 秒，写入为 30 秒），超时时间包括读取响应所花费的时间。

安装

通过 Smithery 安装

通过 Smithery 为 Claude Desktop 自动安装 InfluxDB MCP Server：

npx -y @smithery/cli install @idoru/influxdb-mcp-server --client claude

选项 1：使用 npx 运行（推荐）

# Run directly with npx
INFLUXDB_TOKEN=your_token npx influxdb-mcp-server

选项 2：全局安装

# Install globally
npm install -g influxdb-mcp-server

# Run the server
INFLUXDB_TOKEN=your_token influxdb-mcp-server

选项 3：从源代码安装

# Clone the repository
git clone https://github.com/idoru/influxdb-mcp-server.git
cd influxdb-mcp-server

# Install dependencies
npm install

# Run the server
INFLUXDB_TOKEN=your_token npm start

需要 Node.js 20 或更高版本。

默认情况下，influxdb-mcp-server 使用 stdio 传输。你可以使用 --stdio 显式指定该传输方式，也可以通过提供 --http 选项启动使用 Streamable HTTP 传输的服务器，并可选地指定端口号（默认为 3000）。此模式使用内部 Express.js 服务器；除非指定 --host，否则服务器会监听 127.0.0.1：

# Start with Streamable HTTP transport on default port 3000
INFLUXDB_TOKEN=your_token npm start -- --http

# Start with Streamable HTTP transport on a specific port
INFLUXDB_TOKEN=your_token npm start -- --http 8080

如果你是全局安装或使用 npx，可以运行：

INFLUXDB_TOKEN=your_token influxdb-mcp-server --http
# or explicitly force stdio
INFLUXDB_TOKEN=your_token influxdb-mcp-server --stdio
# or
INFLUXDB_TOKEN=your_token influxdb-mcp-server --http 8080

HTTP 传输安全

任何能够访问 HTTP 端点的人，都可以使用服务器的 INFLUXDB_TOKEN 读取和写入 InfluxDB，因此默认情况下会锁定 HTTP 传输：

• 仅监听 127.0.0.1。
• 在回环地址上，会拒绝 Host 标头不是 localhost、127.0.0.1 或 [::1] 的请求，以阻止浏览器中已打开的网站发起 DNS 重绑定攻击。
• 除非设置了 MCP_AUTH_TOKEN（或 MCP_HTTP_ALLOW_UNAUTHENTICATED=true），否则不会监听任何其他接口。

若要在网络上或从容器中访问服务器，请启用 Bearer 令牌验证：

INFLUXDB_TOKEN=your_token MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  influxdb-mcp-server --http 3000 --host 0.0.0.0

随后，客户端需在每个请求中发送 Authorization: Bearer <MCP_AUTH_TOKEN>。设置 MCP_ALLOWED_HOSTS，以指定客户端访问服务器时使用的主机名，从而加强 DNS 重绑定防护。如果服务器可从你的计算机以外的位置访问，建议在服务器前端终止 TLS。

Docker

镜像以非特权的 node 用户运行，并默认使用 stdio：

docker build -t influxdb-mcp-server .
docker run --rm -i -e INFLUXDB_TOKEN=your_token -e INFLUXDB_URL=http://host.docker.internal:8086 influxdb-mcp-server

# Streamable HTTP inside a container must bind 0.0.0.0, so it needs a token
docker run --rm -p 127.0.0.1:3000:3000 -e INFLUXDB_TOKEN=your_token -e MCP_AUTH_TOKEN=your_mcp_token \
  influxdb-mcp-server --http 3000 --host 0.0.0.0

与 Claude for Desktop 集成

将服务器添加到你的 claude_desktop_config.json：

使用 npx（推荐）

{
  "mcpServers": {
    "influxdb": {
      "command": "npx",
      "args": ["influxdb-mcp-server"],
      "env": {
        "INFLUXDB_TOKEN": "your_token",
        "INFLUXDB_URL": "http://localhost:8086",
        "INFLUXDB_ORG": "your_org",
        "INFLUXDB_BUCKET": "your_bucket"
      }
    }
  }
}

如果是在本地安装

{
  "mcpServers": {
    "influxdb": {
      "command": "node",
      "args": ["/path/to/influxdb-mcp-server/src/index.js"],
      "env": {
        "INFLUXDB_TOKEN": "your_token",
        "INFLUXDB_URL": "http://localhost:8086",
        "INFLUXDB_ORG": "your_org",
        "INFLUXDB_BUCKET": "your_bucket"
      }
    }
  }
}

代码结构

服务器代码采用模块化结构：

• src/
  • index.js - CLI 入口点（参数解析和传输方式选择）
  • server.js - 注册资源、工具和提示词的 MCP 服务器工厂
  • config/ - 配置相关文件
    • env.js - 环境变量处理
    • http.js - HTTP 传输选项和安全检查
  • http/ - Streamable HTTP 传输
    • app.js - Express 应用（Host 验证、Bearer 身份验证、请求体大小限制）
  • utils/ - 实用函数
    • influxClient.js - 带请求超时的 InfluxDB API 客户端
    • csv.js - Flux CSV 响应解析器
    • flux.js - Flux 字符串转义和 URI 参数解码
    • loggerConfig.js - 控制台日志记录器配置和 DEBUG 跟踪
    • traceTransport.js - 用于 DEBUG=mcp:* 的 MCP 消息跟踪
  • handlers/ - 资源和工具处理程序
    • organizationsHandler.js - 组织列表
    • bucketsHandler.js - Bucket 列表
    • measurementsHandler.js - Measurement 列表
    • queryHandler.js - 查询执行
    • writeDataTool.js - 数据写入工具
    • queryDataTool.js - 查询工具
    • createBucketTool.js - Bucket 创建工具
    • createOrgTool.js - 组织创建工具
  • prompts/ - 提示词模板
    • fluxQueryExamplesPrompt.js - Flux 查询示例
    • lineProtocolGuidePrompt.js - 行协议指南

这种结构有助于提高可维护性、简化测试，并清晰地分离关注点。

测试

此代码库包含全面的测试，测试会：

• 启动运行 InfluxDB 的 Docker 容器
• 填充示例数据
• 测试所有 MCP 服务功能
• 在不使用 Docker 的情况下，测试 HTTP 传输的 Host 验证、身份验证和限制，以及 CSV 和 Flux 辅助工具

运行测试：

npm test

许可证

MIT