# jeremiahsay/greencalculus-mcp [Health: Active] **Category:** πŸ“Š Data Platforms **Repository:** https://github.com/jeremiahsay/greencalculus-mcp **GitHub Stars:** 0 **npm Downloads (last month):** 169 **Views:** 1 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/jeremiahsay-greencalculus-mcp ## Description Sourced greenhouse-gas emission factors and audit-traced carbon calculations (activity, embodied EN 15978, PCAF financed emissions) β€” every value returns with its exact source cell and data version, so answers are citable and reproducible. 13,000+ factors, 11 tools. Install: npx -y greencalculus-mcp, or connect remotely at https://mcp.greencalculus.com. Free tier, no card. ## Tools Capabilities this server exposes over MCP: - **lookup_factor** β€” Look up a single greenhouse-gas emission factor by its canonical key. Returns the value plus an audit envelope: provenance (publisher, exact source reference, retrieval date, LICENCE and whether it may be redistributed, with the attribution the licence requires) and verification (whether the per-gas components sum to the headline, the GWP set, and the source note stating what the publisher did NOT provide). If the key does not exist you get candidate keys back rather than a dead end. Use search_factors first if you do not know the key. - **search_factors** β€” Find emission factors by section, key prefix, or free text. Returns each match with its key, name, section, VALUE, unit and gas β€” enough to choose between them or read a few numbers without a second call. For one factor's full audit envelope (publisher, exact source reference, retrieval date, licence, verification) call lookup_factor; for several, call lookup_factors. - **lookup_factors** β€” Look up SEVERAL emission factors by key in one call, each with the same audit envelope lookup_factor returns β€” provenance (publisher, exact source reference, retrieval date, licence, redistribution) and verification. Use this instead of calling lookup_factor in a loop: a portfolio or a multi-country comparison is one call, not one per factor. Keys that do not exist come back in `not_found` rather than failing the batch. - **calculate_activity** β€” Turn activity data into greenhouse-gas emissions: emissions = activity Γ— factor. Give an amount + unit and a factor key; the unit engine converts to the factor basis (MWhβ†’kWh, tonneβ†’kg, gallonβ†’litre, mileβ†’km) and returns the emissions with the working, the GHG Protocol scope, and the source. Use search_factors / lookup_factor to find the factor key. - **calculate_embodied** β€” Whole-life embodied carbon for materials, per EN 15978. Give a material key + quantity (+ optional boundary A1-A3 / A1-A4 / A1-A5 / A1-C); it assembles the declared lifecycle modules (A1-A3, B, C1-C4, D) into stages, totals the boundary, reports module D separately, and flags any missing stage as not-assessed (never zero). Find material keys via search_factors (section "materials"). - **calculate_pcaf** β€” Compute PCAF Part A financed emissions for a portfolio. Returns each holding's attribution factor and financed emissions, the portfolio total, the outstanding-weighted data-quality score, and the audit trail (formula + PCAF source). - **calculate_electricity** β€” GHG Protocol Scope 2 for purchased electricity, both methods. Always returns location-based (grid-average) emissions; also returns market-based when you supply a contractual supplier_factor (e.g. a green tariff / REC = 0) or a market_factor_key (residual mix). Find grid keys via search_factors (section "grid"). - **calculate_freight** β€” Freight & logistics emissions (Scope 3 Cat 4 & 9), GLEC framework. THE FACTOR'S DENOMINATOR PICKS THE METHOD β€” check the factor's unit before choosing the input. Per tonne-km: emissions = tonnes Γ— km Γ— factor, send "mass". Per TEU-km (the sea-container family, e.g. freight_detailed.sea.container.trans_suez.dry): emissions = TEU Γ— km Γ— factor, send "teu" β€” a TEU is a twenty-foot container slot, not a mass, and a forty-foot box is 2 TEU. Sending mass against a per-TEU-km factor is refused (422), not converted. Find mode factors via search_factors (section "freight" or "freight_detailed"), e.g. freight.road_hgv.tonne_km. - **calculate_spend** β€” Spend-based (EEIO) Scope 3 screening: emissions = spend Γ— economic-intensity factor. Spend must be in the factor's own currency/year (no FX). Find sector factors via search_factors (section "spend_based"), e.g. spend_based.us.naics6.541511.custom_computer_programming_services. - **calculate_business_travel** β€” Business travel emissions (Scope 3 Cat 6), distance method: emissions = km Γ— passengers Γ— factor. Air factors come in with_rf / without_rf (radiative forcing) variants. Find factors via search_factors (section "business_travel"). - **resolve_factor** β€” Find the best emission-factor key(s) for a plain-language description β€” the hardest step is picking the right key out of ~16,000. Returns ranked matches, each carrying the key, value, unit and a confidence score; feed the chosen key to a calculate_* tool or lookup_factor. Prefer this over guessing a key. PUT THE COUNTRY IN THE DESCRIPTION. Geography is read from the description text itself, not from a separate field β€” "diesel per litre" and "diesel per litre France" resolve differently, and omitting the country will quietly return a factor from somewhere else marked "geo_match":"proxy". ACT ON THE LABEL. Every candidate carries label: "accept" or "review", plus "why". "accept" means confidence >= 0.85 and no demotion applied β€” right about nine times in ten. "review" means the answer may be usable but something is off (low confidence, only one term matched, a proxy country, or a gate demoted it); confirm it before adopting the number rather than using it silently. Roughly half of CORRECT answers are also flagged "review" β€” that is the intended trade, so treat "review" as "check this", not "discard this". A MISS MAY EXPLAIN ITSELF. When nothing matches, or the only matches are from the wrong country, the response may carry an "absence" object saying WHY. classification "structural" means no publisher issues this anywhere β€” STOP, do not retry with reworded queries and do not substitute a different country without saying so. "not_yet_sourced" means a publisher exists and we have not ingested it (the publisher is named). "refused" means we found the data and declined it, with the reason. "coupled" means this reads empty only because a related family is empty. Use explain_absence to ask the same question directly. - **explain_absence** β€” Ask why a factor is NOT in the corpus. The reasoned counterpart to coverage: where a country reports zero rows for an inventory family, this says whether that is the world's limit or our backlog. Five classifications: "structural" (no publisher issues this anywhere β€” stop looking, and do not silently substitute another country), "not_yet_sourced" (a publisher exists and is named; it is our backlog), "refused" (we found it and declined β€” the reason is stated), "held_not_counted" (we DO hold it β€” see we_hold for the key), "coupled" (empty only because another family is empty). Each record names the publisher checked, the route tried, a confidence and a review date, and reports stale:true once past review. These are authored judgements about what the world publishes, not values derived from our data. Call this before concluding that a gap is permanent, and before telling a user to look elsewhere. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "greencalculus-mcp": { "command": "npx", "args": ["-y","greencalculus-mcp"] } } ``` ## Documentation & README # GreenCalculus MCP server [![CI](https://github.com/greencalculus/greencalculus-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/greencalculus/greencalculus-mcp/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/greencalculus-mcp?label=npm&color=04BF62)](https://www.npmjs.com/package/greencalculus-mcp) [![MCP registry](https://img.shields.io/badge/MCP%20registry-com.greencalculus%2Fapi-04BF62)](https://registry.modelcontextprotocol.io) [![tools](https://img.shields.io/badge/tools-12-04BF62)](#tools) [![free tier](https://img.shields.io/badge/free%20tier-no%20card-04BF62)](https://greencalculus.com/developers/) [![licence](https://img.shields.io/badge/licence-MIT-blue)](./LICENSE) Sourced greenhouse-gas emission factors and audit-traced carbon calculations, as an MCP server. Every value comes back with its exact source reference and a pinned data version β€” so an agent hands back a number a person can cite and a machine can reproduce, instead of a guess. ## Do you need this package? Probably not. **The server is remote**, and if your client speaks remote MCP you should point it straight at the URL β€” nothing to install, nothing to update: ```json { "mcpServers": { "greencalculus": { "url": "https://mcp.greencalculus.com", "headers": { "Authorization": "Bearer YOUR_KEY" } } } } ``` This package exists for the clients that can only spawn a local stdio process, and for `docker run` installs. It is a thin bridge: it forwards each JSON-RPC message to the remote server and returns the reply verbatim. No method is special-cased, so new tools appear here without a release. ## Use it over stdio ```json { "mcpServers": { "greencalculus": { "command": "npx", "args": ["-y", "greencalculus-mcp"], "env": { "GREENCALCULUS_API_KEY": "YOUR_KEY" } } } } ``` Or with Docker β€” the image is published to GitHub Container Registry as `ghcr.io/greencalculus/greencalculus-mcp` (linux/amd64 and arm64, tags `latest` and each version). `-i` is required and `-t` must be omitted, because the container's stdin/stdout *are* the transport and a TTY corrupts the stream: ```json { "mcpServers": { "greencalculus": { "command": "docker", "args": ["run", "-i", "--rm", "-e", "GREENCALCULUS_API_KEY", "ghcr.io/greencalculus/greencalculus-mcp"], "env": { "GREENCALCULUS_API_KEY": "YOUR_KEY" } } } } ``` Get a free key at **https://greencalculus.com/developers** β€” no card. Discovery (`initialize`, `tools/list`) works without one, and so do `search_factors` and `explain_absence`; every other tool needs a key. ## Tools | Tool | What it does | |---|---| | `lookup_factor` | Fetch one emission factor by key, with its source and version | | `lookup_factors` | Fetch many factors by key in one call β€” a portfolio is one request, not one per factor | | `search_factors` | Search the corpus by free text | | `resolve_factor` | Map a messy real-world description to the best-matching factor | | `explain_absence` | Say *why* a factor does not exist, rather than returning nothing | | `calculate_activity` | Activity β†’ emissions, with unit conversion and GHG Protocol scope | | `calculate_electricity` | Location-based and market-based electricity | | `calculate_embodied` | Embodied carbon (EN 15978), explicit about missing lifecycle stages | | `calculate_pcaf` | PCAF financed emissions, with the audit trail | | `calculate_freight` | Freight by mode, distance and load | | `calculate_spend` | Spend-based EEIO | | `calculate_business_travel` | Business travel across modes | ## Configuration | Variable | Default | Meaning | |---|---|---| | `GREENCALCULUS_API_KEY` | β€” | Your API key. `GC_API_KEY` is accepted as an alias; the explicit name wins. | | `GREENCALCULUS_MCP_URL` | `https://mcp.greencalculus.com` | Override the endpoint. | | `GREENCALCULUS_MCP_TIMEOUT_MS` | `120000` | Per-request timeout. | Diagnostics go to stderr. Nothing but JSON-RPC is ever written to stdout β€” a stray byte there corrupts the session. ## Develop ```bash npm test # unit tests, no network node bin/greencalculus-mcp.js # reads JSON-RPC on stdin docker build -t greencalculus-mcp . # local image; CI publishes ghcr.io/greencalculus/greencalculus-mcp ``` ## Releasing Bump `version` in `package.json`, merge to `main`. That's the whole procedure β€” npm, the MCP registry and the container image all follow from it. [`release.yml`](https://github.com/jeremiahsay/greencalculus-mcp/blob/HEAD/.github/workflows/release.yml) asks npm and the MCP registry whether they already have that version and publishes only where they don't, so a merge that bumps ships it and a merge that doesn't is a no-op. It also runs weekly, so a publish that failed is retried without a new commit. `server.json` is the registry manifest, and the workflow rewrites its version from `package.json` before publishing β€” one source of truth, three places that have to agree. npm authenticates by [trusted publishing](https://docs.npmjs.com/trusted-publishers), so there is no npm token here. The registry needs one secret, and the reason is worth knowing: we publish as `com.greencalculus/api`, a DNS namespace, and GitHub OIDC only ever grants `io.github./*`. So the registry step signs with the key matching the `v=MCPv1` TXT record on greencalculus.com, held as `MCP_PRIVATE_KEY`. [`scripts/rotate-registry-key.sh`](https://github.com/jeremiahsay/greencalculus-mcp/blob/HEAD/scripts/rotate-registry-key.sh) generates a fresh pair and installs it without ever printing the private half; it prints the TXT record to publish. Without the secret the registry step skips and says so β€” npm still publishes. ## Also available - **REST API** and docs β€” https://greencalculus.com/developers - **Client SDKs** (Python, JS/TS) β€” https://github.com/greencalculus/greencalculus-sdk - **Official MCP registry** β€” `com.greencalculus/api` - **Smithery** β€” https://smithery.ai/servers/greencalculus/api ## Licence MIT β€” see [LICENSE](https://github.com/jeremiahsay/greencalculus-mcp/blob/HEAD/LICENSE). The licence covers this bridge. Emission-factor data returned by the API carries the licence of its underlying source, which is named in every response.