Costfluent

Costfluent MCP 服务

一个 MCP 服务，可让 AI 助手读取你的 Costfluent 云成本数据：一段时间内的成本、已保存的成本报告、预算、异常、节省队列、承诺及其覆盖情况，以及 Kubernetes 效率。它运行在你的机器上，通过 stdin 和 stdout 与助手通信，并使用你提供的 API 令牌调用 Costfluent Public API。默认情况下，它只读取数据。它的写入工具可创建和更改注释、成本报告、预算、成本提醒和仪表板，确认异常，并设置节省发现项的状态和负责人；只有 Owner 在 Settings、Organization 中启用 Let AI agents create and change objects 后，这些工具才会开放，并且仅限于令牌具备的写入权限。没有任何工具会删除内容或操作云账户。

同一组工具也可以通过终端、脚本或 CI 作业作为 costfluent 命令行工具（命令行）运行。

完整指南：https://docs.costfluent.com/developers/mcp；命令行：https://docs.costfluent.com/developers/cli。

安装

从 最新发布版本下载适用于你平台的归档文件：其中包含 costfluent-mcp 和 costfluent。也可以使用 Go 构建：

go install github.com/costfluent/costfluent-mcp/cmd/costfluent-mcp@latest
go install github.com/costfluent/costfluent-mcp/cmd/costfluent@latest

每个版本的归档文件都附带构建来源证明，并且每个归档文件旁边都有 SPDX SBOM（<archive>.sbom.json），来源证明也涵盖该 SBOM：

gh attestation verify costfluent-mcp_<version>_<os>_<arch>.tar.gz --repo costfluent/costfluent-mcp

对于 Claude Desktop，每个版本还附带 costfluent-mcp_<version>.mcpb，这是一个包含适用于 macOS（Apple silicon 和 Intel）、Windows 和 Linux（x86-64）的服务的 MCP bundle。在 Claude Desktop 中打开该文件，应用会提示你输入 API 令牌。该 bundle 也附带自己的证明，并以相同方式验证。此服务在 MCP Registry 中列为 io.github.costfluent/costfluent-mcp，指向该 bundle。

创建令牌

在 Costfluent 的 Settings、API tokens 中创建 API 令牌。对于助手，建议从 Read only 预设开始并选择有效期限：令牌存放在助手的配置文件中，服务只能执行令牌允许的操作。只有在助手需要调用写入工具时，才添加相应的写入权限。组织设置仅适用于通过此服务或工具命令发出的、带有 Costfluent-Agent 标记的工具请求（costfluent estimate、whoami 和 login 不发送该标记）：任何持有具备写入权限的令牌的人仍可直接调用 API，因此，要确保 Agent 不进行任何更改，就应为其提供不包含这些权限的令牌。

配置助手

服务读取两个环境变量：

变量	含义
COSTFLUENT_API_TOKEN	API 令牌。必需。
COSTFLUENT_BASE_URL	要调用的 API；未设置时为 https://api.costfluent.com。必须使用 https，但 localhost 除外。

服务还会访问另一个主机：search_docs 和 get_doc_page 首次调用时以及此后每小时会读取 https://docs.costfluent.com/llms-full.txt（文档的公开文本），且不使用令牌。如果出口策略限制了助手机器可访问的地址，请允许这两个主机。

Claude Code：

claude mcp add costfluent --env COSTFLUENT_API_TOKEN=<token> -- costfluent-mcp

Claude Desktop、Cursor 和其他读取 mcpServers 文件的客户端：

{
  "mcpServers": {
    "costfluent": {
      "command": "costfluent-mcp",
      "env": { "COSTFLUENT_API_TOKEN": "<token>" }
    }
  }
}

工具

服务会向 API 查询令牌具备哪些权限，以及组织是否允许 AI Agent 创建和更改对象，并且只开放两者都允许的工具。如果令牌不具备下列任何权限，服务会在启动时停止并报错，列出这些权限。工作区令牌默认读取其所属工作区；除非工具另有指定，否则 API 会拒绝访问其他工作区。

工具	功能	权限
list_workspaces	令牌可读取的工作区	viewWorkspace（查看工作区）
query_costs	按日期范围查询成本、用量或资源数量，并进行分组和筛选	viewCosts（查看成本）
list_cost_reports	工作区已保存的成本报告	viewCostReports（查看成本报告）
get_cost_report_data	获取已保存报告当前显示的数据；若报告过大，无法在单次回复中展示，则仅返回最近几个周期的数据	viewCosts（查看成本）
list_annotations	按日期查询工作区的注释：成本报告上的备注，以及预算和成本提醒触发时留下的标记；可按报告或日期范围查询，默认显示未解决的注释，除非指定查询已解决的注释	viewCostReports（查看成本报告）
list_budgets	查询预算及其支出和状态	viewBudgets（查看预算）
list_anomalies	查询检测到的成本异常	viewAnomalies（查看异常）
list_savings_items	查询节省队列中的发现，并按标签页、来源、类型、连接、成本估算涉及的资源或最低月度节省金额筛选	viewSavingsItems（查看节省项）
list_commitments	查询预留、节省计划和承诺使用折扣及其期限和利用率	viewCosts（查看成本）
get_commitment_coverage	按日期范围查询覆盖率、实际节省率和未使用的承诺；默认按月统计，除非另有指定	viewCosts（查看成本）
get_kubernetes_efficiency	按集群、命名空间或工作负载查询成本、闲置成本以及 CPU 和内存效率，最多返回 500 行	viewCosts（查看成本）
create_annotation	在日期对应的已保存成本报告上添加备注	updateCostReport（更新成本报告）
create_cost_report	保存新的成本报告	createCostReport（创建成本报告）
update_cost_report	修改已保存的成本报告；调用中未提供的内容将保留	updateCostReport（更新成本报告）
create_budget	创建预算	createBudget（创建预算）
update_budget	修改预算；调用中未提供的内容（包括提醒）将保留	updateBudget（更新预算）
create_cost_alert	创建成本提醒	manageAlerts（管理成本提醒）
update_cost_alert	修改成本提醒；调用中未提供的内容将保留	manageAlerts（管理成本提醒）
pause_cost_alert	暂停成本提醒	manageAlerts（管理成本提醒）
resume_cost_alert	恢复已暂停的成本提醒	manageAlerts（管理成本提醒）
create_dashboard	创建仪表板	createDashboard（创建仪表板）
add_dashboard_widget	向仪表板添加组件；API 还会检查「查看成本报告」权限	updateDashboard（更新仪表板）
acknowledge_anomaly	确认检测到的成本异常	acknowledgeAnomaly（确认异常）
set_savings_item_status	将节省项标记为已接受、已实施或已拒绝；拒绝时需填写原因	respondToSavingsItem（响应节省项）
assign_savings_item_owner	设置节省项的负责人	manageSavingsItems（管理节省项）
search_docs	搜索 Costfluent 文档（英文或德文），查找回答问题的相关章节，例如如何使用 Terraform 管理预算	无
get_doc_page	以 Markdown 格式读取 Costfluent 文档中的页面或某个章节	无
当 API 拒绝调用时，助手会收到 API 返回的错误，包括状态、代码和详情；组织设置拒绝写入时，响应为 403 agent_writes_disabled。每个写入工具都会标记为会更改内容，因此，会在此类调用前征求确认的客户端会询问你；设置为自动批准工具调用的客户端则不会。工具结果是数据，每个写入工具的说明都会告知助手，绝不要因为结果中的文字提出请求就更改内容。令牌的请求配额适用于每次调用；对于短暂的限流，服务会等待限制解除，对于持续时间较长的限流，则会报告相关信息。

命令行

costfluent 会将每个工具作为命令运行：工具名称使用连字符，参数作为带连字符的标志，并执行相同的能力检查、验证和结果处理。它会从相同的两个变量中读取令牌和基础 URL。

export COSTFLUENT_API_TOKEN=<token>
costfluent whoami
costfluent query-costs --start-date 2026-10-01 --end-date 2026-10-31 --group-by ServiceName
costfluent list-budgets --output json | jq '.items[] | select(.state == "over")'
costfluent query-costs --help

你也可以不使用令牌，而是通过 costfluent login 在浏览器中登录，并为一个组织批准只读访问权限；登录信息会保存在操作系统的凭据存储中（macOS Keychain、Linux 上的 Secret Service、Windows Credential Manager）。之后运行命令时无需设置 COSTFLUENT_API_TOKEN，但如果该变量已设置，则会优先使用它。在没有凭据存储的计算机上，costfluent login --insecure-storage 会将登录信息保存在 XDG_CONFIG_HOME 或系统配置目录下的 costfluent/credentials.json 中，只有你本人可以读取。--no-browser 会打印供你打开的网址。costfluent logout 会撤销登录并清除登录信息。

如果标准输出不是终端，它会打印 JSON；如果是终端，则会打印表格；使用 --output json 或 --output table 可选择输出格式。需要接收列表的标志（例如 --group-by）可重复指定。成功时退出码为 0，调用失败时为 1，命令行错误时为 2，令牌缺失、遭拒或缺少命令所需能力时为 3，超过你设置的阈值时为 4；错误会输出到标准错误流；如果不是终端，则会以 API 错误 JSON 的形式输出。

costfluent mcp install --client <client> 会打印用于在 Claude Code（claude-code）、Cursor（cursor）、Codex（codex）、VS Code（vscode）或 Copilot CLI（copilot）中启动 costfluent-mcp 的配置项；添加 --write 会将其写入相应客户端的文件，同时保留其中的其他所有服务。配置项中不包含令牌：客户端会从 COSTFLUENT_API_TOKEN 读取令牌，或者由 VS Code 提示你输入。若客户端启动时未设置该变量，--write --embed-token 会将令牌本身写入配置项，并将文件设为只有你本人可以读取；请勿将该文件纳入版本控制。

costfluent estimate submit 会提交 Infracost 为任意 CI 中的 Terraform 拉取请求生成的估算，并采用 Costfluent 成本估算 GitHub Action 使用的转换方式；costfluent estimate apply 会记录变更已应用，并附上状态为其创建或替换的资源分配的 ID。这些命令需要具有 Submit cost estimates 能力的令牌；如果计划中的月度变更超过 --fail-above 指定的阈值，则会在打印回执后以退出码 4 退出。

costfluent estimate submit --workspace-id wsp_8f3k2m --repository acme/infra --pull-request 42 \
  --infracost-json infracost.json --terraform-plan-json plan.json --fail-above 500
costfluent estimate apply --workspace-id wsp_8f3k2m --repository acme/infra --pull-request 42 \
  --terraform-plan-json plan.json --terraform-state-json state.json

许可证

Apache-2.0