CrbonFreeCrbonFree
@crbonfree/mcpv0.3.6Build on your numbers

Give your AI agent eyes on your carbon footprint.

Seven read-only tools hand the emissions, usage and receipts your dashboard already holds to Claude Desktop, Cursor, Claude Code, Windsurf or any MCP client. You ask in plain language and the answer comes back with the numbers behind it.

Sign in once

npx @crbonfree/mcp login
View on npmRead the API reference
illustrative session, example numbers

7

read-only tools, none of them writes

4,500+

SDK and MCP downloads with no paid marketing

Crbon Labs, 2026

3

parameters on the reporting tools: dates and project

12

public API operations behind the tools

What is the MCP server?

The CrbonFree MCP server, published as @crbonfree/mcp on npm, is a Model Context Protocol server with seven read-only tools. Running beside Claude Desktop, Cursor, Claude Code, Windsurf or any MCP client, it lets an agent answer questions about your AI emissions, usage, projects and credit retirement receipts from the same API the dashboard reads, using the key that login saved.

Last checked against the product on 5 September 2026. Carbon figures follow methodology v1.2.

At a glance
Package
@crbonfree/mcp on npm
Version
0.3.6
Licence
MIT
Requires
Node.js 18 or newer
Transport
stdio JSON-RPC
Tools
7, all reads, no writes
Authenticates with
~/.crbonfree/credentials, or CRBONFREE_API_KEY
Clients
Claude Desktop, Cursor, Claude Code, Windsurf, any MCP client

Seven tools, every one of them a read

Two reporting tools, get_emissions_summary and get_usage_breakdown, return totals and per-model detail for a date range. The other five list your projects, page through your credit retirement receipts, fetch one receipt by ID and report the retirement status of the current billing period. None of them writes, deletes or changes billing.

  • Questions that map to one call

    Both reporting tools accept start_date, end_date and project_id, so a question like "how much did the support bot emit last month" becomes a single call with three arguments. Leave the dates out and the summary covers the last 30 days.

  • Runs beside the client you already use

    The server speaks stdio JSON-RPC, the transport every MCP client supports, so Claude Desktop, Cursor, Claude Code and Windsurf each configure it with one mcpServers entry. It runs on your machine, starts when your client does, and calls the CrbonFree API over HTTPS with your saved key.

  • Receipts and retirement status on request

    Ask for the current billing period and you get its lifecycle state, the CO2 retired, the amount charged and, once issued, the receipt with its verification and PDF links. Individual receipts come back by ID with their serial numbers, dates and amounts, ready to hand to whoever asked.

How the MCP server moves your data

  1. 1

    You ask in plain language

    A question like “how much did the support bot emit last month” goes to your agent as it normally would.

  2. 2

    The agent picks a tool

    It calls get_emissions_summary with a start date, an end date and the project ID, or list_projects first if it needs the ID.

  3. 3

    The server calls the API

    Over HTTPS with the key that login saved, to the same endpoints the dashboard reads. Nothing is computed locally.

  4. 4

    The agent answers with the numbers

    Totals, lower and upper bounds and per-model detail come back, and the agent phrases the answer.

How to get started

  1. 1

    Sign in once

    Opens the browser, signs you in or creates an account, generates an API key and saves it to ~/.crbonfree/credentials with owner-only permissions. It needs Node 18 or newer, and the package is MIT licensed.

    npx @crbonfree/mcp login
  2. 2

    Add it to your client

    In Claude Code it is one command. Claude Desktop, Cursor, Windsurf and any other MCP client take the same server as an mcpServers entry that runs npx with the arguments -y and @crbonfree/mcp. No environment variable is needed; the server finds the key that login saved.

    claude mcp add crbonfree -- npx -y @crbonfree/mcp
    Other clients: { "mcpServers": { "crbonfree": { "command": "npx", "args": ["-y", "@crbonfree/mcp"] } } }
  3. 3

    Ask a question

    Ask "How much CO2 did the support bot produce last month?" and the agent calls get_emissions_summary with a start_date, an end_date and the project_id, then answers from the totals and per-model rollups that come back. If it does not know the project ID yet, list_projects gives it one.

    get_emissions_summary
  start_date  2026-08-01
  end_date    2026-08-31
  project_id  <your project id>
    The call behind that question. Dates are YYYY-MM-DD.

The same numbers as your dashboard

Every answer comes from the CrbonFree API that the dashboard reads, so a figure your agent quotes matches the one on the emissions page for the same range and project. The server does no arithmetic of its own; it hands the API response to your agent and lets the agent phrase the answer.

See the dashboard in the sample account

What it does not do

Everything it does is a read. The seven tools return usage, emissions, projects, receipts and retirement status that the backend has already computed, and none of them writes, deletes or changes a plan. It does not meter or ingest anything, so usage has to reach CrbonFree through a provider connection or the CLI before the server has anything to report. It needs the API key that login saves, or CRBONFREE_API_KEY in the environment, and it speaks stdio only, which means it runs beside a local client rather than as a hosted endpoint.

Who reaches for the MCP server

Developer in an editor

Wants last month’s emissions for a project without leaving Claude Code or Cursor.

What they get: One question runs get_emissions_summary and returns totals with their bounds.

Sustainability officer

Asks an assistant for the current billing period’s retirement status before a board update.

What they get: get_current_retirement_status returns the period state, the CO2 retired and the receipt once it is issued.

Operations lead

Needs a specific receipt, with serial numbers, to attach to an internal ticket.

What they get: list_carbon_receipts finds it and get_carbon_receipt returns the serial numbers, dates and amounts.

Which CrbonFree surface do I need?

Three of them put usage in: the dashboard through provider connections, the CLI for coding agents and the browser extension for chat sessions. The other four read the numbers back into your own code. The MCP server is highlighted.

SurfaceMeters usageReads numbers backRunsNeedsLanguage
DashboardIn the browserAn account; the sample account opens without oneNone
CLI statusOn your machineAn account; device code for headless machinesNode 20 or newer
Browser extension estimatesIn ChromeOptional, per the store listingNone
TypeScript SDKNode 18 or newerAn API keyTypeScript or JavaScript
Python SDKPython 3.8 or newerAn API keyPython
MCP serverthis pageBeside your MCP clientAn API key from loginAny MCP client
REST APIOver HTTPSAn API keyAny

Questions

Questions about the MCP server.

Short answers. The package page and the API reference have the long ones.

View on npm

  • The server is free and MIT licensed. It reads whatever your plan holds; usage and carbon estimates are on the free plan, and receipts and audit packs come with the paid plans.

  • Not today. It speaks stdio only, so it runs beside a local MCP client rather than as a shared service. Each person signs in once with npx @crbonfree/mcp login.

  • Claude Desktop, Cursor, Claude Code and Windsurf are documented, and any client that can launch a stdio MCP server works the same way. The configuration is identical everywhere: run npx with the arguments -y and @crbonfree/mcp.

  • No. All seven tools are reads. There are no mutations, no deletions and no billing changes, so an agent holding this server can look at your numbers but cannot alter them.

  • Login saves the API key to ~/.crbonfree/credentials on your machine, readable only by your user, and the server reads that file on startup. If you would rather manage the key yourself, set CRBONFREE_API_KEY in the environment and it takes precedence. Run npx @crbonfree/mcp logout to remove the saved file.

Goes well with

All products
DashboardEvery provider, project and coding agent in one report. The sample account opens without a login.CLIMeter your local AI coding agents automatically, synced to the dashboard every hour.Browser extensionEstimates token usage in your AI chat sessions across ChatGPT, Gemini and the Claude apps, including Claude Code. Guest mode keeps everything on your machine, and signing in keeps the history.

See your own number instead of ours.

However your team already runs AI, that is how you connect. Paste a read-only provider key, drop in an SDK, add the MCP server, install the CLI or switch on the browser extension, and the first measured tokens reach your dashboard within seconds.

Create your free account

Free plan · first tokens in seconds