MCP server
Let an AI assistant such as Claude Code or Cursor read your costs, cost reports, budgets and anomalies through the Costfluent MCP server and a read-only API token.
The Costfluent MCP server lets an AI assistant answer questions about your cloud spend without you opening the app. It runs on your machine, speaks the Model Context Protocol to the assistant over stdin and stdout, and calls the Public API with an API token you give it. It only reads: no tool creates, changes or deletes anything.
Before you start
Available on the Starter, Core, Optimize and Scale plans. Compare plans
- Creating the token needs the Owner, Integration Owner or Editor organization role; see API authentication.
- The assistant must support local MCP servers that run as a command, as Claude Code, Claude Desktop and Cursor do.
Create a token
- Open Settings, then API tokens, and select Create API token.
- Enter a Name that says which assistant uses the token, such as
Claude Code on my laptop. - Under Access, choose the workspace the assistant works in, so the token reaches nothing else. Keep Whole organization only when the assistant compares workspaces.
- Under Start from, choose Read only. Clear any capability the assistant does not need: the tools need View workspaces, View costs, View cost reports, View budgets and View anomalies.
- Choose an Expiration, such as 90 days, and select Create API token.
- Copy the token from Your API token. It is shown only once.
The token is stored in your assistant's configuration file, in plain text. Give it only read capabilities and an expiration, and revoke it under API tokens when you stop using the assistant.
Install the server
Download the archive for your platform from the latest release and put costfluent-mcp on your PATH, or build it with Go:
Code
Each release carries a build provenance attestation, which gh attestation verify <archive> --repo costfluent/costfluent-mcp checks.
Connect your assistant
The server reads COSTFLUENT_API_TOKEN, the token, and optionally COSTFLUENT_BASE_URL, which defaults to https://api.costfluent.com and must use https.
- In Claude Code, run
claude mcp add costfluent --env COSTFLUENT_API_TOKEN=<token> -- costfluent-mcp. - In Claude Desktop, Cursor or another client with an
mcpServersfile, add the server as below. - Restart the assistant and ask it a question, such as "What did we spend on AWS last month, by service?".
Code
Tools
| Tool | What it reads | Capability |
|---|---|---|
list_workspaces | The workspaces the token can read | View workspaces |
query_costs | Cost, usage or resource count over a date range, per day, week, month or quarter, grouped by up to three dimensions and narrowed by a cost filter | View costs |
list_cost_reports | A workspace's saved cost reports | View cost reports |
get_cost_report_data | The numbers a saved report shows now | View costs |
list_budgets | Budgets with their current spend and state | View budgets |
list_anomalies | Detected cost anomalies, newest first | View anomalies |
How it behaves
- At start the server asks the API which capabilities its token carries, and offers the assistant only the tools those capabilities allow. A token the API refuses stops the server with the API's error.
- Workspace tools need a
workspace_idwith an organization token; the assistant finds the IDs withlist_workspaces. A workspace token reads its own workspace unless 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, and can explain it or adjust the question.
- Every call counts against the token's request limit. The server waits out a short limit and returns a longer one to the assistant.
- The server never writes the token to its log or to a tool result; it travels only in the request header.