# iLEAP MCP

**A Model Context Protocol (MCP) server for iLEAP — bring trusted logistics
emissions data into any AI assistant.**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/protocol-MCP-6E56CF.svg)](https://modelcontextprotocol.io)
[![iLEAP](https://img.shields.io/badge/standard-iLEAP_v1.1.0-0A7E3E.svg)](https://specs.ileap.global/)
[![PACT](https://img.shields.io/badge/interoperable-PACT-1E88E5.svg)](https://www.carbon-transparency.org/)

`ileap-mcp` is an open, standalone MCP server that exposes
[iLEAP](https://specs.ileap.global/) and
[PACT](https://www.carbon-transparency.org/) emissions data to any MCP client —
Claude, ChatGPT connectors, Kiro, Cursor, and the rest. Point it at any
iLEAP-conformant endpoint and your AI assistant can list product footprints,
inspect transport activity data, and submit events using natural language,
without anyone writing a bespoke API integration.

It ships preconfigured against the public
[SINE Foundation iLEAP demo endpoint](https://api.ileap.sine.dev), so you can
try it end to end in minutes — no credentials of your own required.

> [!WARNING]
> **Demo-quality code.** This is a pure, unauthenticated proxy to a public
> iLEAP demo endpoint. It carries no secrets, applies no inbound
> authentication, and does no rate limiting — because the upstream credentials
> and the proxied data are public. **Do not deploy it to production in front of
> non-public data without hardening it first** (a real upstream credential kept
> in a secret store, an inbound authorizer on `/mcp`, and rate limiting at
> minimum). We are releasing it deliberately lean to lower the barrier to
> adoption, and we will strengthen the security posture if the community calls
> for it. Contributions in that direction are welcome.

---

## Why this exists

Logistics is a large, hard-to-see slice of most products' carbon footprint. The
**iLEAP** standard — free to implement, open source, and software-friendly —
lets trustworthy emissions data flow across transport modes and organizations,
aligned with **ISO 14083** and the **GLEC Framework v3.1**, and interoperable
with **PACT**.

AI assistants are quickly becoming how people query and reason over operational
data. `ileap-mcp` is the bridge: it turns a conformant iLEAP HTTP API into a set
of MCP tools an assistant can call directly. The goal is to lower the barrier to
adoption for the whole iLEAP community — implementers, software providers,
shippers, and carriers — so that "ask your assistant about your logistics
emissions" becomes a one-command setup.

## What it does

The server wraps the endpoints an iLEAP-conformant host serves and exposes each
as an MCP tool:

| MCP tool | iLEAP / PACT endpoint | Data type |
| --- | --- | --- |
| `list_footprints` | `GET /2/footprints` | PACT ProductFootprint (list, paginated) |
| `get_footprint` | `GET /2/footprints/{id}` | PACT ProductFootprint (single) |
| `list_tad` | `GET /2/ileap/tad` | iLEAP Transport Activity Data |
| `post_event` | `POST /2/events` | PACT event (the one write surface) |

Authentication to the upstream endpoint uses OpenID discovery + OAuth2
client-credentials; pagination follows the RFC 8288 `Link` cursor convention
required by the specs. The server is transport-agnostic on the client side: it
speaks **Streamable-HTTP** for hosted deployments and **stdio** for local use.

## Quick start

### Try it in 60 seconds (against the SINE demo)

Build and run the container locally, talking to the live demo endpoint:

```shell
$ docker build -t ileap-mcp .
$ docker run --rm -p 8080:8080 \
    -e ILEAP_BASE_URL=https://api.ileap.sine.dev \
    -e ILEAP_CLIENT_ID=hello \
    -e ILEAP_CLIENT_SECRET=pathfinder \
    ileap-mcp

$ curl http://127.0.0.1:8080/healthz
{"status":"ok","upstream":"https://api.ileap.sine.dev"}
```

The MCP endpoint is then reachable at `http://127.0.0.1:8080/mcp`.

### Add it to your MCP client

Point any MCP client at the running server. For a local stdio setup:

```json
{
  "mcpServers": {
    "ileap": {
      "command": "python",
      "args": ["-m", "ileap_mcp.server"],
      "env": {
        "ILEAP_MCP_STDIO": "1",
        "ILEAP_BASE_URL": "https://api.ileap.sine.dev",
        "ILEAP_CLIENT_ID": "hello",
        "ILEAP_CLIENT_SECRET": "pathfinder"
      }
    }
  }
}
```

For a hosted server over HTTPS:

```json
{
  "mcpServers": {
    "ileap": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-host.example.com/mcp"]
    }
  }
}
```

### Run from source

```shell
$ git clone https://github.com/bernard357/ileap-mcp.git
$ cd ileap-mcp
$ cp .env.example .env          # defaults target the SINE demo
$ make setup                    # create venv, install deps
$ make run                      # serve Streamable-HTTP on :8080
```

## Point it at your own endpoint

`ileap-mcp` is a swappable client — the same tools work against any conformant
iLEAP host. Change the environment and you are done:

| Variable | Purpose | Default |
| --- | --- | --- |
| `ILEAP_BASE_URL` | Upstream iLEAP/PACT base URL | `https://api.ileap.sine.dev` |
| `ILEAP_CLIENT_ID` | OAuth2 client id | `hello` |
| `ILEAP_CLIENT_SECRET` | OAuth2 client secret | `pathfinder` |
| `ILEAP_HOST` | Bind address for HTTP transport | `0.0.0.0` |
| `ILEAP_PORT` | Bind port for HTTP transport | `8080` |
| `ILEAP_MCP_STDIO` | Set to `1` to run stdio instead of HTTP | _(unset)_ |

## Deployment

The server is a plain container and runs anywhere containers run — locally via
`docker run`, or on any container platform. See [`DEPLOYMENT.md`](DEPLOYMENT.md)
for building the image, configuration, and running it in production. The
repository is a clean, self-contained server that anyone can build and run on
the platform of their choice.

## Standards and conformance

- **iLEAP Technical Specifications v1.1.0** — <https://specs.ileap.global/>
- **PACT** (Partnership for Carbon Transparency, WBCSD) —
  <https://www.carbon-transparency.org/>
- **ISO 14083:2023** and the **GLEC Framework v3.1** — the methodological basis
- **Automated Conformance Testing (ACT)** — <https://act.sine.dev/>

This project is a client of the iLEAP protocol; it does not redefine the
standard. Where behavior is ambiguous, the specifications are authoritative.

## Community and contributing

`ileap-mcp` is built to be adopted and extended by the iLEAP community. Whether
you implement iLEAP, provide logistics software, or just want your assistant to
speak emissions data, contributions are welcome.

- **Discuss and propose** — open a
  [GitHub Discussion](https://github.com/bernard357/ileap-mcp/discussions)
  or an [issue](https://github.com/bernard357/ileap-mcp/issues).
- **Contribute code** — read [`CONTRIBUTING.md`](CONTRIBUTING.md) for the dev
  setup, coding conventions, test expectations, and the pull-request flow. Good
  first areas: additional iLEAP data types, richer filtering, client-side
  auth strategies, and conformance test coverage.
- **Be kind** — participation is governed by our
  [Code of Conduct](CODE_OF_CONDUCT.md).

We review pull requests openly and aim to keep the project a neutral, useful
piece of shared infrastructure for the whole iLEAP ecosystem.

## Origin and stewardship

`ileap-mcp` grew out of conversations within the iLEAP community, where the idea
of a concrete, shared contribution — a standard way to bring logistics emissions
data into AI assistants — resonated with other members. This project is that
contribution: a standalone, vendor-neutral MCP server that anyone can run, fork,
and build on.

It is maintained by [Bernard Paques](https://github.com/bernard357) and is kept
deliberately independent of any single platform, so it stays useful shared
infrastructure for the whole iLEAP ecosystem.

Questions or anything else: **bernard.paques@gmail.com**.

## License

Licensed under the [MIT License](LICENSE). You are free to use, modify, and
distribute this software, including commercially, subject to the terms of the
license.

## Acknowledgements

Thanks to the [SINE Foundation](https://sine.foundation/) and the
[Smart Freight Centre](https://www.smartfreightcentre.org/) for developing and
openly sharing the iLEAP standard and the public demo endpoint this project
targets, and to WBCSD PACT for the underlying data-exchange protocol.