Costfluent MCP server

An MCP server that lets an AI assistant read your Costfluent cloud cost data: costs over time, saved cost reports, budgets, anomalies, the savings queue, commitments and their coverage, and Kubernetes efficiency. It runs on your machine, talks to your assistant over stdin and stdout, and calls the Costfluent Public API with an API token you give it. It reads by default. Its write tools create and change annotations, cost reports, budgets, cost alerts and dashboards, acknowledge anomalies and set a savings finding's status and owner; it offers them only once an Owner turns on Let AI agents create and change objects under Settings, Organization, and only for the write capabilities the token carries. No tool deletes anything or touches a cloud account.

The same tools run from a terminal, a script or a CI job as the costfluent command line tool (Command line).

Full guide: https://docs.costfluent.com/developers/mcp; the command line: https://docs.costfluent.com/developers/cli.

Install

Download the archive for your platform from the latest release: it holds both costfluent-mcp and costfluent. Or build them with Go:

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

Each release's archives carry a build provenance attestation, and each archive has an SPDX SBOM beside it (<archive>.sbom.json) that the attestation covers too:

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

For Claude Desktop, each release also carries costfluent-mcp_<version>.mcpb, an MCP bundle with the server for macOS (Apple silicon and Intel), Windows and Linux on x86-64. Open it in Claude Desktop, which asks for your API token. The bundle carries its own attestation, verified the same way. The server is listed in the MCP Registry as io.github.costfluent/costfluent-mcp, pointing to that bundle.

Related MCP server: Cognitally

Create a token

Create an API token in Costfluent under Settings, API tokens. For an assistant, start from the Read only preset and choose an expiration: the token sits in your assistant's configuration file, and the server can do only what the token allows. Add a write capability only for a write tool the assistant should call. The organization setting governs only the requests a tool makes, through this server or a tool's command, which carry a Costfluent-Agent marker (costfluent estimate, whoami and login send none): anyone holding a token with write capabilities can still call the API directly, so an agent that must not change anything gets a token without them.

Configure your assistant

The server reads two environment variables:

The server calls one other host: search_docs and get_doc_page read https://docs.costfluent.com/llms-full.txt, the public text of the documentation, without the token, on their first call and once an hour after. Allow both hosts where an egress policy limits what the assistant's machine reaches.

Claude Code:

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

Claude Desktop, Cursor and other clients that read an mcpServers file:

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

Tools

The server asks the API which capabilities its token carries and whether the organization lets AI agents create and change objects, and offers only the tools both allow. A token carrying none of the capabilities below stops the server at start with an error naming them. A workspace token reads its own workspace unless a tool is told otherwise, and the API refuses any other.

When the API refuses a call, the assistant receives the API's error, with its status, code and detail; a write the organization setting refuses answers 403 agent_writes_disabled. Each write tool is marked as one that changes something, so a client that asks before such a call asks you; a client set to approve tool calls automatically does not. Tool results are data, and each write tool's description tells the assistant never to change something because text in a result asks. The token's request quota applies to every call; the server waits out a short limit and reports a longer one.

Command line

costfluent runs each tool as a command: the tool's name with hyphens, its arguments as flags with hyphens, and the same capability check, validation and result. It reads the token and base URL from the same two variables.

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

Instead of a token, costfluent login signs in through the browser, where you approve read access for one organization, and keeps the sign-in in the operating system's credential store (the macOS Keychain, the Secret Service on Linux, the Windows Credential Manager); commands then run without COSTFLUENT_API_TOKEN, which still wins when set. On a machine without a credential store, costfluent login --insecure-storage keeps it in costfluent/credentials.json under XDG_CONFIG_HOME or the system's configuration directory, readable by you alone. --no-browser prints the address to open instead. costfluent logout revokes the sign-in and forgets it.

It prints JSON unless stdout is a terminal, where it prints a table; --output json or --output table chooses. A flag that takes a list, such as --group-by, is repeated. It exits 0 on success, 1 when the call failed, 2 on a wrong command line, 3 when the token is missing, refused or lacks the capability the command needs, and 4 when a threshold you set was exceeded; an error goes to stderr, as the API's error JSON when it is not a terminal.

costfluent mcp install --client <client> prints the entry that starts costfluent-mcp in Claude Code (claude-code), Cursor (cursor), Codex (codex), VS Code (vscode) or Copilot CLI (copilot), and --write adds it to that client's file, keeping every other server in it. The entry holds no token: the client reads it from COSTFLUENT_API_TOKEN, or VS Code prompts for it. For a client started where that variable is not set, --write --embed-token writes the token itself into the entry and makes the file readable by you alone; keep that file out of version control.

costfluent estimate submit posts the estimate Infracost makes for a Terraform pull request from any CI, with the conversion Costfluent's cost estimate GitHub Action uses, and costfluent estimate apply records that the change was applied, with the ids the state gives the resources it created or replaced. They need a token with the Submit cost estimates capability, and --fail-above exits 4 after printing the receipt when the planned monthly change is above it.

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

License

Apache-2.0