The GreenCalculus MCP server provides sourced greenhouse gas emission factors and auditable carbon calculations, exposed as an MCP server. Its core characteristic is that every returned value carries a precise source citation and a pinned data version, so the numbers an agent returns can both be cited by humans and reproduced by machines, rather than being a guessed value.
Purpose and positioning The service targets AI agent scenarios that need carbon emission factors and carbon calculation capabilities, covering calculation types such as activity emissions, embodied carbon (EN 15978), and PCAF financed emissions, with source citations and data versions attached.
Main capabilities
- Provides sourced greenhouse gas emission factors.
- Provides carbon calculations with an auditable trail.
- Every value returns a precise source citation and a pinned data version.
- Supports discovery methods initialize and tools/list, as well as tools such as search_factors and explain_absence.
How to use The server is remote. If the client supports remote MCP, it should point directly at the URL, with no installation and no updates. The package in this repository exists for clients that can only launch a local stdio process and for docker run installation scenarios; it is a lightweight bridge: it forwards each JSON-RPC message to the remote server and returns the reply as-is, without special handling for any method, so new tools can appear here without a release.
Use it via stdio, or use Docker: the image is published on the GitHub Container Registry at ghcr.io/greencalculus/greencalculus-mcp (supporting linux/amd64 and arm64, with tags latest and per-version). When using Docker you must add -i and must not add -t, because the container's stdin/stdout is the transport channel, and a TTY will corrupt the data stream.
Keys and access You can get a free key at https://greencalculus.com/developers , with no credit card required. Discovery methods (initialize, tools/list) work without a key, and search_factors and explain_absence also require no key; all other tools require a key.
Diagnostics and output Diagnostic information is written to stderr. stdout carries only JSON-RPC; any extra bytes will corrupt the session.
Release process Bump the version in package.json and merge to main, and npm, the MCP registry, and the container image will all update accordingly. release.yml first asks npm and the MCP registry whether they already have that version, and publishes only where it is missing, so a merge that bumps the version publishes, while a merge that does not bump the version is a no-op. The workflow also runs weekly, and failed publishes are retried automatically without a new commit. server.json is the registry manifest, and before publishing the workflow rewrites its version number from package.json, achieving a single source of truth kept consistent in three places. npm authenticates via trusted publishing, so there is no npm token in the repository. The registry requires a key because: publishing uses the DNS namespace com.greencalculus/api, while GitHub OIDC only grants io.github.<org>/*, so the registry step signs with a key matching the v=MCPv1 TXT record on greencalculus.com, stored in MCP_PRIVATE_KEY. scripts/rotate-registry-key.sh can generate a new key pair and install it, and never prints the private key portion, while printing the TXT record that needs to be published. If that key is missing, the registry step is skipped with an explanation, and npm still publishes.
Related resources
- REST API and documentation: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
License MIT, see LICENSE. This license covers this bridge package. The emission factor data returned by the API follows the license of its underlying sources, and the source name is noted in each response.
