greencalculus/greencalculus-mcp

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:
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
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:
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
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 asks npm and the MCP registry
whether they already have that version and publishes only where they don't, so