# TerraTwin MCP Server

Calculate freight shipment greenhouse gas (GHG) emissions directly from Claude using the [TerraTwin](https://www.terratwin.com) API. Calculations follow the **GLEC Framework** and **EN 16258** standard across all transport modes — road, sea, air, and rail.

---

## Features

- **All major transport modes** — ROAD, WATER (sea/inland), AIR, RAIL, and multi-modal chains
- **GLEC Tier 1 and Tier 2** calculations — default factors or operational vehicle data
- **Full WTW lifecycle reporting** — Well-to-Tank (WTT), Tank-to-Wheel (TTW), and Well-to-Wheel (WTW) breakdown per leg and in total
- **Emission intensity** — g CO₂e/tonne-km alongside absolute kg CO₂e
- **FTL and LTL emission allocation** — correct load-factor allocation for Less-Than-Truckload shipments
- **Smart routing** — automatic RoRo ferry insertion on Scandinavia–Europe road corridors, automatic road pre/post-carriage for sea and rail legs
- **Multi-leg journeys** — submit complete transport chains (e.g. road feeder → hub → ocean → hub → road delivery)
- **Domain guidance built in** — the tool description encodes GLEC rules (empty running convention, payload vs. gross weight, FTL vs. LTL) so Claude asks the right questions before calling the API

---

## Setup

### Prerequisites

- A TerraTwin account with an active API key — obtain one at [terratwin.com/account/settings/api-key-manager](https://www.terratwin.com/account/settings/api-key-manager)
- Claude Desktop, Claude.ai, or Claude Code

### Connecting to the server

Add the TerraTwin MCP server to your Claude client configuration. The server is available at:

```
https://mcp.terratwin.com/mcp
```

#### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "terratwin": {
      "type": "http",
      "url": "https://mcp.terratwin.com/mcp"
    }
  }
}
```

#### Claude.ai (web)

1. Go to **Settings → Integrations → Add custom integration**
2. Enter the server URL: `https://mcp.terratwin.com/mcp`
3. Save and enable the integration

#### Claude Code (CLI)

```bash
claude mcp add terratwin --transport http https://mcp.terratwin.com/mcp
```

### Authentication

The server uses **OAuth 2.0 authorization code flow with PKCE**.

When you connect for the first time, Claude will open a browser window to the TerraTwin authorization page. Enter your TerraTwin API key to grant access. Claude will then receive a Bearer token that it uses for all subsequent requests — you do not need to enter your API key again until the token expires (1 hour; automatic refresh keeps you connected for up to 30 days).

Your API key is transmitted only to the TerraTwin API (`api.terratwin.com`) and is never logged or stored by the MCP server beyond the lifetime of your session token.

**Get your API key:** [terratwin.com/account/settings/api-key-manager](https://www.terratwin.com/account/settings/api-key-manager)

#### OAuth redirect URIs to allowlist on your hosting platform

```
https://claude.ai/api/mcp/auth_callback
https://claude.com/api/mcp/auth_callback
http://localhost:6274/oauth/callback
http://localhost:6274/oauth/callback/debug
```

#### Local development (no browser)

Set `MCP_AUTH_DISABLED=true` to bypass OAuth and pass your API key directly in the tool `apiKey` field:

```bash
MCP_AUTH_DISABLED=true npm run dev
```

---

## Usage Examples

### Example 1 — Road shipment with automatic RoRo ferry routing (GLEC Tier 1)

**Prompt:**
> Move 1,000 kg by truck from Oslo to Berlin.

**What Claude does:**
- No load type specified → defaults to LTL and warns that a GLEC default load factor was applied
- Detects two auto-inserted RoRo ferry crossings in the response and explains the routing

**Actual output:**

| Metric | Value |
|--------|-------|
| WTW Total CO₂e (headline) | **208.97 kg** |
| TTW (direct combustion) | 167.39 kg |
| WTT (upstream fuel / production) | 41.58 kg |
| Emission intensity | 210.28 g CO₂e / tonne-km |
| Route distance | 993.8 km |
| Activity | 993.8 tonne-km |
| Vehicle class | Heavy Duty Vehicle |
| GLEC Tier | 1 (default intensity factors) |

TerraTwin automatically routed this shipment via two RoRo ferry crossings, which is standard for Oslo–Berlin truck corridors:

| Leg | Mode | Route | Distance | CO₂e |
|-----|------|-------|----------|------|
| 1 | Road | Oslo → Helsingborg (SE) | 512.4 km | 64.0 kg |
| 2 | RoRo Ferry | Helsingborg → Helsingør (DK) | 5.2 km | 8.9 kg |
| 3 | Road | Helsingør → Gedser (DK) | 192.0 km | 24.0 kg |
| 4 | RoRo Ferry | Gedser → Rostock (DE) | 48.4 km | 82.5 kg |
| 5 | Road | Rostock → Berlin | 235.8 km | 29.5 kg |

> The Gedser–Rostock ferry is the most emissions-intensive leg per tonne-km due to Marine Diesel Oil (MDO) emission factors applied to RoRo vessels.

> **Assumption:** calculated as LTL by default. A GLEC default load factor was applied internally — not disclosed in the response. For a dedicated truck (FTL) or if you know the actual load factor, Claude can recalculate with more accurate results.

---

### Example 2 — Simple road shipment, pure road routing (GLEC Tier 1)

**Prompt:**
> Move 500 kg by truck from Amsterdam to Paris.

**What Claude does:**
- No load type specified → defaults to LTL and warns that a GLEC default load factor was applied
- No sub-mode insertion on this corridor — pure road result

**Actual output:**

| Metric | Value |
|--------|-------|
| WTW Total CO₂e (headline) | **31.59 kg** |
| TTW (direct combustion) | 24.30 kg |
| WTT (upstream fuel / production) | 7.29 kg |
| Emission intensity | 125 g CO₂e / tonne-km |
| Route distance | 505.4 km |
| Activity | 252.7 tonne-km |
| Vehicle class | Heavy Duty Vehicle (diesel) |
| GLEC Tier | 1 (default intensity factors) |

> **Assumption:** calculated as LTL by default. A GLEC default load factor was applied internally — not disclosed in the response. For a dedicated truck (FTL) or a known load factor, Claude will recalculate with more accurate results.

---

### Example 3 — Ocean freight with automatic door-to-door chain (GLEC Tier 1)

**Prompt:**
> Now let's do Hamburg to Miami by WATER transporting about 1,000 kg.

**What Claude does:**
- Selects WATER mode and builds a full door-to-port-to-door chain automatically
- Detects auto-inserted road pre-carriage (Hamburg) and post-carriage (Miami) plus port hub emissions
- Highlights the sea vs. road intensity contrast from the previous calculation

**Actual output:**

| Metric | Value |
|--------|-------|
| WTW Total CO₂e (headline) | **74.32 kg** |
| TTW (direct combustion) | 60.63 kg |
| WTT (upstream fuel / production) | 13.68 kg |
| Hub emissions (port terminals) | 0.003 kg |
| Emission intensity | 9.29 g CO₂e / tonne-km |
| Total distance | 7,997 km |
| Activity | 7,997 tonne-km |
| GLEC Tier | 1 (default intensity factors) |

TerraTwin automatically built the full door-to-port-to-door chain:

| Segment | Vehicle | Distance | WTW CO₂e |
|---------|---------|----------|----------|
| Pre-carriage (Hamburg) | Heavy Duty Truck | 14.9 km | 1.86 kg |
| Port terminal (Hamburg) | Maritime Terminal Hub | — | ~0.001 kg |
| Ocean leg | Container Ship (ultra-large, VLSFO) | 7,977 km | 71.95 kg |
| Port terminal (Miami) | Maritime Terminal Hub | — | ~0.001 kg |
| Post-carriage (Miami) | North American Dray truck | 5.2 km | 0.50 kg |

> **Sea vs. road efficiency:** this ocean voyage (1,000 kg, ~8,000 km) emits only 74 kg CO₂e at 9.3 g/tonne-km — versus 32 kg for a 500 kg truck shipment over just 505 km at 125 g/tonne-km. Maritime shipping is dramatically more carbon-efficient per tonne-km, which is why it dominates global trade from an emissions perspective.

---

### Example 4 — Tier 2 road calculation (operational vehicle data)

**Prompt:**
> Calculate truck emissions from Hamburg to Warsaw for 5,000 kg of auto parts. We use an articulated truck: 40 t maximum weight, 14 t tare, 80% load factor, 30% empty running. Dedicated truck — we have the whole vehicle.

**What Claude does:**
- Recognises "dedicated truck" → FTL; rejects any load factor in this context (as per GLEC rules)  
  *(Note: for FTL, the full vehicle emissions are assigned to this shipment regardless of fill)*
- Computes payload: 40 t − 14 t = 26 t
- Constructs a `transportChain` ROAD leg with operational parameters for Tier 2
- Returns:

```
WTW total:   ~245 kg CO₂e
  TTW:       ~195 kg CO₂e
  WTT:        ~50 kg CO₂e

Intensity:   ~49 g CO₂e/tonne-km
Distance:    ~1,010 km  |  Activity: ~5.05 tonne-km
GLEC Tier: 2 (operational parameters applied)
Vehicle class: ARTICULATED_TRUCK_34000_TO_40000_KG
Empty running: 30% of total km (GLEC definition) → total distance ~1,443 km modelled
```

---

### Example 5 — Multi-modal transport chain

**Prompt:**
> We ship 2,000 kg of machinery from our warehouse in Lyon, France to a customer in Gothenburg, Sweden — first by truck to Marseille port, then by sea to Gothenburg. What are the total CO₂e emissions?

**What Claude does:**
- Builds a multi-leg `transportChain`: ROAD (Lyon → Marseille) + WATER (Marseille → Gothenburg)
- Submits both legs in a single API request
- Returns consolidated WTW total plus per-leg breakdown

```
WTW total:   ~185 kg CO₂e
  Road leg (Lyon → Marseille):   ~22 kg CO₂e
  Sea leg (Marseille → Gothenburg): ~163 kg CO₂e

GLEC Tier: 1  |  Distance: ~2,650 km total
```

---

## Available tools

| Tool | Description | Safety |
|------|-------------|--------|
| `terratwin_calculate_shipment_co2` | Calculate GHG emissions for a freight shipment across any transport mode | Read-only — queries the TerraTwin API, no data is written |

## Available prompts

| Prompt | Description |
|--------|-------------|
| `shipment-co2` | Guided workflow: Claude gathers all required inputs before calling the tool |

---

## GLEC Framework compliance

All calculations follow the **Global Logistics Emissions Council (GLEC) Framework v3** and **EN 16258**:

| Tier | Data required | What TerraTwin applies |
|------|--------------|------------------------|
| **Tier 1** | Mode + distance only | GLEC default intensity factors per vehicle class |
| **Tier 2** | Vehicle weights, load factor, empty running | Operational parameters override default factors |
| **Tier 3** | Actual fuel consumption (L/100 km) | Primary measured data *(API support pending)* |

WTW = WTT + TTW is the standard reporting scope per GLEC / EN 16258.

---

## Privacy

See the [TerraTwin Privacy Policy](https://www.terratwin.com/legal/privacy-policy) for details on data handling.  
The MCP server forwards calculation requests to the TerraTwin API. No conversation content is stored.

---

## Support

Email: **team@terratwin.com**  
MCP documentation: [mcp.terratwin.com](https://mcp.terratwin.com)  
API documentation: [docs.terratwin.com](https://docs.terratwin.com)

---

## Terms

Use of the TerraTwin API is subject to the [TerraTwin Terms of Service](https://www.terratwin.com/legal/terms-of-use).