@climeqai/mcp-server
Official# `@climeqai/mcp-server` — Official ClimeqAI & VALENQ Engine MCP Server
[](https://modelcontextprotocol.io)
[](https://climeqai.com/docs?lang=en)
[](https://nodejs.org)
[](#)
[](./LICENSE)
Official zero-dependency **Model Context Protocol (MCP)** stdio server connecting **Claude Desktop**, **Cursor**, **Windsurf**, **VS Code GitHub Copilot**, **Google Antigravity**, and custom AI agents directly to **[ClimeqAI](https://climeqai.com)** — the Autonomous Sustainability Operating System powered by **VALENQ Engine**.
- **Website:** [https://climeqai.com](https://climeqai.com)
- **Live Platform (Free Core Tier):** [https://climeqai.com/signup](https://app.climeqai.com/signup)
- **API & MCP Documentation:** [https://climeqai.com/docs?lang=en](https://climeqai.com/docs?lang=en)
- **OpenAPI 3.1 Schema:** [`schemas/openapi.json`](./schemas/openapi.json) (`https://app.climeqai.com/assets/api/openapi.json`)
- **Postman Collection v2.1:** [`schemas/climeqai.postman_collection.json`](./schemas/climeqai.postman_collection.json) (`https://app.climeqai.com/assets/api/climeqai.postman_collection.json`)
---
## Key Capabilities
1. **VALENQ Engine Autonomous Mapping (`v1`):** Map unstructured ERP invoice lines, utility bills, and Bill-of-Materials (BOM) items to verified scientific emission factors with confidence scoring, data quality indicators, and automated inflation adjustment.
2. **Global & Custom Private Datasets:** Search global emission factor libraries or register tenant-isolated custom private emission factors.
3. **Domain & Enterprise Carbon Calculators:** Deterministic Scope 1, 2, and 3 calculations across electricity (location-based and market-based renewable certificates), fuels/biofuels, district heat/steam, multimodal freight, procurement spend, air travel, commuting, and cloud infrastructure (`AWS`, `Azure`, `GCP`).
4. **Product Impact Studio (LCA) & Cross-Border Carbon Declarations:** Model cradle-to-gate and cradle-to-grave Product Carbon Footprints (from BOMs or BOM-less AI screening) and estimate cross-border embedded carbon liabilities.
5. **Blockchain Digital Product Passports (DPP Vault):** Verify QR-linked, blockchain-sealed Digital Product Passports (`climeq_verify_dpp`) without requiring an API key.
---
## Quick Start
### Option A: Zero-Install Single-File Setup (Recommended)
Download the standalone zero-dependency `.mjs` executable directly:
```bash
mkdir -p ~/.climeqai
curl -fsSL https://app.climeqai.com/assets/api/climeqai-mcp-server.mjs \
-o ~/.climeqai/climeqai-mcp-server.mjs
```
### Option B: Clone from GitHub
```bash
git clone https://github.com/climeqai/mcp-server.git
cd mcp-server
node --test ./test/mcp-server.test.mjs
```
---
## Getting Your API Key
1. Sign in or create a free account at **[https://app.climeqai.com/signup](https://app.climeqai.com/signup)** (*ClimeqAI Core includes 250 monthly API/MCP requests free — no credit card required*).
2. Navigate to **Security → API Keys** in the left sidebar.
3. Generate an M2M API Key (`sust_<48_hex_characters>`).
*(Note: The `climeq_verify_dpp` tool queries public GS1 Digital Product Passports and works even without an API key.)*
---
## MCP Client Configuration
### 1. Claude Desktop (`claude_desktop_config.json`) & Cursor (`.cursor/mcp.json`)
```json
{
"mcpServers": {
"climeqai": {
"command": "node",
"args": ["/Users/YOUR_USERNAME/.climeqai/climeqai-mcp-server.mjs"],
"env": {
"CLIMEQ_API_KEY": "sust_your_48_character_hex_api_key",
"CLIMEQ_BASE_URL": "https://app.climeqai.com",
"CLIMEQ_DATA_VERSION": "^2026.1"
}
}
}
}
```
### 2. VS Code / GitHub Copilot (`.vscode/mcp.json`)
```json
{
"servers": {
"climeqai": {
"type": "stdio",
"command": "node",
"args": ["/Users/YOUR_USERNAME/.climeqai/climeqai-mcp-server.mjs"],
"env": {
"CLIMEQ_API_KEY": "${input:climeqApiKey}",
"CLIMEQ_BASE_URL": "https://app.climeqai.com"
}
}
}
}
```
### 3. Google Antigravity (`~/.gemini/config/mcp_config.json`)
```json
{
"mcpServers": {
"climeqai": {
"command": "node",
"args": ["/Users/YOUR_USERNAME/.climeqai/climeqai-mcp-server.mjs"],
"env": {
"CLIMEQ_API_KEY": "sust_your_48_character_hex_api_key",
"CLIMEQ_BASE_URL": "https://app.climeqai.com",
"CLIMEQ_DATA_VERSION": "^2026.1"
}
}
}
}
```
---
## Environment Variables
| Variable | Required | Default | Description |
| :--- | :--- | :--- | :--- |
| `CLIMEQ_API_KEY` | Yes *(except `climeq_verify_dpp`)* | — | M2M API Key (`sust_<48_hex>`) created in **Security → API Keys** |
| `CLIMEQ_BASE_URL` | No | `https://app.climeqai.com` | Target ClimeqAI API base URL |
| `CLIMEQ_DATA_VERSION` | No | `^2026.1` | Default emission factor catalog version selector |
| `CLIMEQ_TIMEOUT_MS` | No | `30000` | HTTP request timeout in milliseconds |
---
## Included MCP Tools (23 Tools)
| Category | MCP Tool Name | REST Endpoint | Description |
| :--- | :--- | :--- | :--- |
| **Catalog & Discovery** | `climeq_search_factors` | `GET /data/search` | Search global datasets and tenant-owned private factors |
| **Catalog & Discovery** | `climeq_list_unit_types` | `GET /data/unit-types` | List physical unit families & supported ISO 4217 currencies |
| **Catalog & Discovery** | `climeq_list_regions` | `GET /data/regions` | List ISO countries, zones & hierarchical geographic fallback chains |
| **Catalog & Discovery** | `climeq_list_data_versions` | `GET /data/versions` | List catalog release versions, factor counts & changelogs |
| **Private Factors** | `climeq_list_private_factors` | `GET /private-factors` | List tenant-private supplier EPD / primary factors |
| **Private Factors** | `climeq_create_private_factor` | `POST /private-factors` | Register a tenant-isolated supplier EPD factor |
| **VALENQ Engine v1** | `climeq_valenq_suggest` | `POST /mapping-agent/suggest` | Rank candidate factors with PACT `dqi`, `top1Explanation` & `notices[]` |
| **VALENQ Engine v1** | `climeq_valenq_estimate` | `POST /mapping-agent/estimate` | Autonomous mapping + compound CPI (`applyInflationAdjustment`) estimation |
| **VALENQ Engine v1** | `climeq_valenq_estimate_batch` | `POST /mapping-agent/estimate/batch` | Batch AI mapping & calculation for up to 100 ERP/BOM items |
| **VALENQ Engine v1** | `climeq_estimate_by_classification` | `POST /classifications/estimate` | Calculate from `UNSPSC`, `NAICS`, `ISIC`, `NACE`, `MCC`, `HS_CODE` |
| **Core Ledger** | `climeq_calculate_emission` | `POST /emissions/calculate` | Deterministic selector, custom rules, `persist` & SHA-256 blockchain proof |
| **Energy** | `climeq_calculate_electricity` | `POST /energy/electricity` | Scope 2 Location + AIB Residual Mix (`YEK-G`/`I-REC`/`GO`) + Scope 3.3 FERA |
| **Energy** | `climeq_calculate_fuel` | `POST /energy/fuel` | Scope 1 fuels, biofuel blends (`B7`, `HVO100`, `SAF`) & `H2` |
| **Energy** | `climeq_calculate_heat_steam` | `POST /energy/heat` | Scope 2 district heating, steam, cooling & distribution thermal losses |
| **Logistics & Spend** | `climeq_calculate_intermodal_freight` | `POST /freight/intermodal` | ISO 14083 / GLEC v3.2 multimodal freight & transshipment hubs |
| **Logistics & Spend** | `climeq_calculate_procurement_spend` | `POST /procurement/spend` | EXIOBASE Basic Price margin stripping + IMF WEO CPI deflation |
| **Travel & Commuting** | `climeq_calculate_air_travel` | `POST /travel/air` | IATA Great-Circle air travel with separate ISO 14083 `RFI` disclosure |
| **Travel & Commuting** | `climeq_calculate_commuting` | `POST /travel/commuting` | Scope 3.7 employee commuting & teleworking home electricity |
| **Product & Enterprise** | `climeq_calculate_pcf` | `POST /pcf/estimate` | ISO 14067 / WBCSD PACT BOM-based Product Carbon Footprint |
| **Product & Enterprise** | `climeq_screen_pcf_ai` | `POST /pcf/screen` | AI BOM-less Product Carbon Footprint screening |
| **Product & Enterprise** | `climeq_estimate_cbam_liability` | `POST /cbam/estimate` | EU CBAM (`2023/956`) embedded emissions & net EUR certificate liability |
| **Product & Enterprise** | `climeq_calculate_cloud_carbon` | `POST /cloud/calculate` | AWS, Azure & GCP operational + hardware embodied carbon |
| **GS1 / W3C DPP** | `climeq_verify_dpp` | `GET /api/public/dpp/*` | Public GS1 Digital Link (`gtin` + `serial`) Digital Product Passport resolver |
---
## Example Prompts for Your AI Assistant
- **ERP Spend Batch Audit:**
> *"Run these 15 SAP purchase order lines through `climeq_valenq_estimate_batch` for spend year 2026, highlight any lines with `qualityLabel: review` or `notices`, and summarize total tCO2e."*
- **EU CBAM Import Liability:**
> *"Use `climeq_estimate_cbam_liability` to compute the 2026 net payable CBAM certificate cost in EUR for 250 metric tons of hot-rolled steel coils (`CN 7208`) imported from `TR`."*
- **Product Carbon Footprint (LCA) Screening:**
> *"Use `climeq_screen_pcf_ai` to estimate the Cradle-to-Gate carbon footprint of a 1.45 kg enterprise aluminum laptop manufactured in `TW` and air-freighted to `DE`."*
- **Multimodal Freight Footprint:**
> *"Calculate the well-to-wheel (`WTW`) emissions for shipping 18 tons of machinery from Istanbul (`TR`) to Hamburg (`DE`) via road + container ship using `climeq_calculate_intermodal_freight`."*
---
## OpenAPI 3.1 & Client SDK Generation
This repository also includes the official OpenAPI 3.1 specification ([`schemas/openapi.json`](./schemas/openapi.json)) and Postman Collection ([`schemas/climeqai.postman_collection.json`](./schemas/climeqai.postman_collection.json)):
```bash
# Generate TypeScript (Fetch) Client SDK
npx @openapitools/openapi-generator-cli generate \
-i ./schemas/openapi.json \
-g typescript-fetch \
-o ./sdk/typescript
# Generate Python (Pydantic v2) Client SDK
npx @openapitools/openapi-generator-cli generate \
-i ./schemas/openapi.json \
-g python \
-o ./sdk/python
```
---
## License
Licensed under the [Apache License, Version 2.0](./LICENSE). Copyright © 2026 ClimeqAI (`https://climeqai.com`).
TDQS
Scored across 23 tools
Most tools target a distinct scope/input type (electricity, fuel, freight, air travel, spend, PCF, CBAM, cloud), so an agent can generally pick correctly. The main gray zones are the generic climeq_calculate_emission vs climeq_valenq_estimate vs climeq_estimate_by_classification, and climeq_calculate_pcf vs climeq_screen_pcf_ai, where the boundary depends on input format rather than purpose.
All tools share a climeq_ prefix and snake_case with a predictable verb_noun shape (list_regions, calculate_fuel, verify_dpp), which is easy to parse. Minor deviation: the valenq_* trio uses a product namespace instead of a verb, and 'screen' vs 'calculate' vs 'estimate' are semantically close.
23 tools is on the heavy side, but the domain is genuinely broad (GHG Protocol scopes 1/2/3, PCF, CBAM, cloud, DPP) and each calculation tool covers a distinct methodology. Nothing looks like filler, though a couple of the general-purpose estimation tools could be folded into the core calculate tool.
Read paths for reference data and a wide set of calculation verbs are covered, but the private-factor lifecycle is create+list only with no update/delete, and there is no visible way to read back persisted calculations or ledger entries that climeq_calculate_emission writes. These are notable gaps that would force agents into dead ends for maintenance and reporting workflows.