{
  "markdown": "# GreenCalculus MCP server\n\n[![CI](https://github.com/greencalculus/greencalculus-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/greencalculus/greencalculus-mcp/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/greencalculus-mcp?label=npm&color=04BF62)](https://www.npmjs.com/package/greencalculus-mcp)\n[![MCP registry](https://img.shields.io/badge/MCP%20registry-com.greencalculus%2Fapi-04BF62)](https://registry.modelcontextprotocol.io)\n[![tools](https://img.shields.io/badge/tools-12-04BF62)](#tools)\n[![free tier](https://img.shields.io/badge/free%20tier-no%20card-04BF62)](https://greencalculus.com/developers/)\n[![licence](https://img.shields.io/badge/licence-MIT-blue)](./LICENSE)\n\nSourced 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.\n\n## Do you need this package?\n\nProbably 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:\n\n```json\n{\n  \"mcpServers\": {\n    \"greencalculus\": {\n      \"url\": \"https://mcp.greencalculus.com\",\n      \"headers\": { \"Authorization\": \"Bearer YOUR_KEY\" }\n    }\n  }\n}\n```\n\nThis 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.\n\n## Use it over stdio\n\n```json\n{\n  \"mcpServers\": {\n    \"greencalculus\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"greencalculus-mcp\"],\n      \"env\": { \"GREENCALCULUS_API_KEY\": \"YOUR_KEY\" }\n    }\n  }\n}\n```\n\nOr 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:\n\n```json\n{\n  \"mcpServers\": {\n    \"greencalculus\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"-i\", \"--rm\", \"-e\", \"GREENCALCULUS_API_KEY\", \"ghcr.io/greencalculus/greencalculus-mcp\"],\n      \"env\": { \"GREENCALCULUS_API_KEY\": \"YOUR_KEY\" }\n    }\n  }\n}\n```\n\nGet 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.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `lookup_factor` | Fetch one emission factor by key, with its source and version |\n| `lookup_factors` | Fetch many factors by key in one call — a portfolio is one request, not one per factor |\n| `search_factors` | Search the corpus by free text |\n| `resolve_factor` | Map a messy real-world description to the best-matching factor |\n| `explain_absence` | Say *why* a factor does not exist, rather than returning nothing |\n| `calculate_activity` | Activity → emissions, with unit conversion and GHG Protocol scope |\n| `calculate_electricity` | Location-based and market-based electricity |\n| `calculate_embodied` | Embodied carbon (EN 15978), explicit about missing lifecycle stages |\n| `calculate_pcaf` | PCAF financed emissions, with the audit trail |\n| `calculate_freight` | Freight by mode, distance and load |\n| `calculate_spend` | Spend-based EEIO |\n| `calculate_business_travel` | Business travel across modes |\n\n## Configuration\n\n| Variable | Default | Meaning |\n|---|---|---|\n| `GREENCALCULUS_API_KEY` | — | Your API key. `GC_API_KEY` is accepted as an alias; the explicit name wins. |\n| `GREENCALCULUS_MCP_URL` | `https://mcp.greencalculus.com` | Override the endpoint. |\n| `GREENCALCULUS_MCP_TIMEOUT_MS` | `120000` | Per-request timeout. |\n\nDiagnostics go to stderr. Nothing but JSON-RPC is ever written to stdout — a stray byte there corrupts the session.\n\n## Develop\n\n```bash\nnpm test                      # unit tests, no network\nnode bin/greencalculus-mcp.js # reads JSON-RPC on stdin\ndocker build -t greencalculus-mcp .   # local image; CI publishes ghcr.io/greencalculus/greencalculus-mcp\n```\n\n## Releasing\n\nBump `version` in `package.json`, merge to `main`. That's the whole procedure — npm, the MCP registry and the container image all follow from it.\n\n[`release.yml`](.github/workflows/release.yml) asks npm and the MCP registry\nwhether they already have that version and publishes only where they don't, so\na merge that bumps ships it and a merge that doesn't is a no-op. It also runs\nweekly, so a publish that failed is retried without a new commit.\n\n`server.json` is the registry manifest, and the workflow rewrites its version\nfrom `package.json` before publishing — one source of truth, three places that\nhave to agree.\n\nnpm authenticates by [trusted publishing](https://docs.npmjs.com/trusted-publishers),\nso there is no npm token here. The registry needs one secret, and the reason is\nworth knowing: we publish as `com.greencalculus/api`, a DNS namespace, and GitHub\nOIDC only ever grants `io.github.<org>/*`. So the registry step signs with the key\nmatching the `v=MCPv1` TXT record on greencalculus.com, held as `MCP_PRIVATE_KEY`.\n[`scripts/rotate-registry-key.sh`](./scripts/rotate-registry-key.sh) generates a\nfresh pair and installs it without ever printing the private half; it prints the\nTXT record to publish. Without the secret the registry step skips and says so —\nnpm still publishes.\n\n## Also available\n\n- **REST API** and docs — https://greencalculus.com/developers\n- **Client SDKs** (Python, JS/TS) — https://github.com/greencalculus/greencalculus-sdk\n- **Official MCP registry** — `com.greencalculus/api`\n- **Smithery** — https://smithery.ai/servers/greencalculus/api\n\n## Licence\n\nMIT — see [LICENSE](./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.\n",
  "bytes": 6077,
  "sha": "df427447b36194cfd32ee02aa91c9689b95c923a1bde1316ddc779a881a870ce",
  "repo_slug": "greencalculus/greencalculus-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_greencalculus_api_38a5376e/readme"
}