jeremiahsay/greencalculus-mcp

Sourced greenhouse-gas emission factors and audit-traced carbon calculations, as an MCP server. Every value comes back with its exact source cell 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:

{
  "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

{
  "mcpServers": {
    "greencalculus": {
      "command": "npx",
      "args": ["-y", "greencalculus-mcp"],
      "env": { "GREENCALCULUS_API_KEY": "YOUR_KEY" }
    }
  }
}

Or with Docker — -i is required and -t must be omitted, because the container's stdin/stdout are the transport and a TTY corrupts the stream:

{
  "mcpServers": {
    "greencalculus": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GREENCALCULUS_API_KEY", "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

npm test                      # unit tests, no network
node bin/greencalculus-mcp.js # reads JSON-RPC on stdin
docker build -t greencalculus/mcp .

Also available

• REST API and docs — https://greencalculus.com/developers
• Client SDKs (Python, JS/TS) — https://github.com/jeremiahsay/greencalculus-sdk
• Official MCP registry — com.greencalculus/api
• Smithery — https://smithery.ai/servers/greencalculus/api

Licence

MIT — see 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.