AI Footprint

io.github.nickjlamb由 GitHub 账号 nickjlamb 发布v1.0.4更新于 Oct 26, 2026

Water and energy footprint of AI use: chat prompts, agent sessions, methodology and sources.

已验证Streamable HTTP可网页运行数据与分析AI 与机器学习

概览

AI 生成的概览

托管式只读 MCP 服务器，用于估算 AI 聊天提示与智能体会话所消耗的水和电，并提供方法论与日常类比。

可以做什么
  • 按使用强度与核算边界，估算每日或一段时间的聊天提示能耗与水耗
  • 根据输入、输出与缓存 token 数估算智能体或编程会话的足迹，并给出区间
  • 把水量换算成茶匙、瓶装水、淋浴时间及生命周期物品等日常类比
  • 返回每条提示的数值、边界、来源、局限与引用格式，并解释公开估算为何相差悬殊
适用场景
适合让助手回答 AI 使用的水耗或能耗问题、核对已发布的数字，或根据 token 用量报告编程或智能体会话的足迹。
运行要求
远程 streamable HTTP 端点，无需安装、API 密钥或账号。任何支持远程 streamable HTTP 的 MCP 客户端均可连接。自托管为可选项，需要 Python。
安装前请注意
数值是基于厂商数据与未经同行评审来源的指示性估算，并非实测；会话结果是假设值并附带区间。托管服务为只读，日志仅记录工具名而不记录输入或 IP，但请求仍会发送到第三方服务器。

安装

在 SourceWeft 中

  1. 打开 控制台中的 AI Footprint，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Web executable，通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。

交给智能体安装

把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体，或 SourceWeft 对话中。智能体会读取该服务器的安装指南，先向你展示发布者、端点和登录方式，经你同意后再把它添加到你的客户端。密钥不会写进任何命令。

阅读 https://sourceweft.com/mcp/io.github.nickjlamb%2Fai-footprint/install.md，并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前，先告诉我它的发布者、端点和登录方式，等我确认。不要把 API 密钥写进命令或我会提交的文件；问我密钥应从哪里获取。

查看智能体所依据的安装指南

其他 MCP 客户端

把它添加到你客户端的 mcpServers 配置中。

{
  "mcpServers": {
    "ai-footprint": {
      "type": "http",
      "url": "https://footprint.pharmatools.ai/mcp"
    }
  }
}

README

[AI Footprint: how much water and energy does AI use? Answers with the boundary, assumptions and sources attached.]

[CI] [Release] [MCP Registry] [Hosted endpoint] [Python 3.10 to 3.13] [Methodology 2026-10] [License: MIT]

Quick start · Tools · Examples · Architecture · Methodology · Roadmap · Contributing

AI Footprint is an MCP server and JSON API that estimates the water and energy used by AI: chat prompts, a year of use, or a whole agent session from its token counts. It's the engine behind the PharmaTools.AI AI Water & Energy Calculator, exposed as tools an agent can call.

Published per-prompt estimates of AI water use range from 0.3 mL to 50 mL. Most of that spread is explainable: when the figure was measured, where the accounting boundary is drawn, what kind of workload is counted, and whose data centre it is. So every answer from this server says which boundary it uses, which assumptions it made and which methodology version it comes from. A figure can be checked rather than repeated.

  • Deterministic. No model in any tool. It's arithmetic over a published, versioned methodology: same input, same answer.
  • Zero setup. A hosted, read-only endpoint. No API key, no install, no account.
  • Pinned to its source. The test suite holds the server's outputs identical to the calculator page.

Quick start

Under 60 seconds, from any MCP client. Add the hosted endpoint:

https://footprint.pharmatools.ai/mcp

Claude Code

bash
claude mcp add --transport http ai-footprint https://footprint.pharmatools.ai/mcp

Claude Desktop and claude.ai: Settings → Connectors → Add custom connector, then paste the URL.

Cursor (~/.cursor/mcp.json)

json
{  "mcpServers": {    "ai-footprint": { "url": "https://footprint.pharmatools.ai/mcp" }  }}

Anything else: any client that supports remote MCP servers over streamable HTTP. Point it at the URL above.

Then ask:

How much water do 30 ChatGPT prompts a day use over a working year?

text
estimate_ai_footprint(queries_per_day=30, days=250)
→ 2.6 kWh and 10.5 L over 250 days (comprehensive boundary)  per prompt: 0.34 Wh, 1.39 mL · about 25.5 hrs of TV or 170 phone charges  methodology 2026-10 · source: pharmatools.ai/water-consumption-calculator

Not using MCP? The same tools are plain GET endpoints:

bash
curl "https://footprint.pharmatools.ai/api/footprint?queries_per_day=30&days=250"

Tools

ToolAsk itReturns
estimate_ai_footprint"30 prompts a day for a year"Energy and water per prompt, per day and in total, with everyday equivalents and assumptions. Usage tier simple (~0.34 Wh), mixed (~1 Wh) or intensive (~3 Wh); boundary onsite or comprehensive.
estimate_session_footprint"200k input, 3M cached, 40k output tokens"A central estimate and a 0.3–3× range for an agent or coding session, plus how many typical chat prompts it equals.
compare_water_use"Is 500 mL a lot?"Teaspoons, bottles and shower time, plus lifecycle items (A4 sheet, almond, tea, burger) with the caveat that those use a much wider boundary.
get_methodology"Why do estimates vary so much?"Per-prompt figures, both boundaries, sources, limitations, a citation line, and four reasons published estimates differ by ~100×.

All four are annotated read-only, idempotent and closed-world, so clients can tell they're safe to call. More in examples/: a Python MCP client, a dependency-free JavaScript client, curl for every endpoint and full captured responses.

Architecture

mermaid
flowchart LR    A["MCP clients<br/>Claude · Cursor · agents"] -->|/mcp| R    B["Scripts and browsers"] -->|/api/*| R    C["Calculator page<br/>pharmatools.ai"] -->|/tighten · /read-claim| R
    subgraph app["One ASGI app · server/main.py"]        R{{"Path router<br/>CORS · rate limits"}}        R -->|"open CORS · 120/min"| M["MCP tools<br/>FastMCP, streamable HTTP"]        R -->|"open CORS · 120/min"| J["JSON API<br/>FastAPI GET routes"]        R -->|"pharmatools.ai only · daily caps"| T["Prompt tightener"]        M --> F[("footprint.py<br/>constants · sources · arithmetic")]        J --> F    end
    T --> H["Claude Haiku"]
  • One source of truth. server/footprint.py holds every constant, source and calculation. The MCP tools and the JSON API are thin wrappers, so they can't drift apart, and the tests hold both to the calculator page's figures.
  • Two security postures in one app. The footprint routes are public arithmetic: open CORS, 120 requests per minute per client. /tighten spends API credit, so it accepts the calculator page only, behind per-IP and global daily caps. A small ASGI wrapper picks the right policy by path.
  • Stateless. No database and no sessions. The MCP server runs in stateless JSON-response mode, so any instance can answer any request. Rate limits are in memory, which assumes a single instance (see the roadmap).
  • Private by default. Logs record tool or endpoint names only. Inputs, prompts and IP addresses are not logged.

Methodology

Energy first, water derived from it.

FigureBasis
Energy, simple text prompt~0.34 WhOpenAI's per-query figure; Google reports a median Gemini text prompt at 0.24 Wh (2025)
Energy, image or long reasoning~3 Wh or moreMIT Technology Review analysis (2025)
Water, onsite boundary~1.0 mL/WhData-centre cooling only, as implied by Google's disclosure. The highest of the published provider figures is used.
Water, comprehensive boundary~4.1 mL/WhAdds ~3.1 mL/Wh consumed generating the electricity (US grid average, Li et al.)
Typical text prompt~0.34 mL onsite, ~1.4 mL comprehensiveThe widely quoted 2023 estimates describe hardware that no longer exists

Session estimates are calibrated so ~1,000 input + ~400 output tokens on a frontier model equals one typical prompt (0.34 Wh), with output tokens costing ~5× input and cache reads ~0.1×. These are assumptions, not measurements, so the tool returns a range and says so.

Limitations. Vendor figures aren't peer-reviewed, describe median prompts and exclude training. Electricity-generation water uses US grid averages. Results are indicative estimates.

Sources. Google (2025) · OpenAI per-query figures · Li et al., Making AI Less Thirsty · MIT Technology Review (2025) · Water Footprint Network

The full write-up is on the calculator page. When the methodology changes, METHODOLOGY_VERSION is bumped and the change is recorded in the changelog. Found a better source? Open a methodology issue.

JSON API

The same four tools as GET endpoints with open CORS. GET /api lists them.

EndpointParameters
/api/footprintqueries_per_day (required), usage=simple|mixed|intensive, boundary=onsite|comprehensive, days
/api/sessioninput_tokens, output_tokens (required), cached_input_tokens, model_class=small|frontier|reasoning, boundary
/api/comparewater_ml (required)
/api/methodologynone

Invalid input returns 400 with a message saying what's allowed. Responses are cacheable for an hour. The limit is 120 requests per minute per client.

Self-hosting

bash
git clone https://github.com/nickjlamb/ai-footprint && cd ai-footprint/serverpip install -r requirements.txtMOCK=1 uvicorn main:app --port 8000# MCP at http://localhost:8000/mcp · JSON API at http://localhost:8000/api

MOCK=1 makes the tightener return a canned rewrite, so no Anthropic key is needed. The footprint tools don't use a key either way. The included Procfile runs as is on Railway, Render, Heroku and similar platforms.

Configuration
VariableDefaultPurpose
ANTHROPIC_API_KEYnoneRequired for /tighten unless MOCK=1
MOCKunset1 returns a canned tightener response
MODELclaude-haiku-4-5Model for the tightener
ALLOWED_ORIGINShttps://www.pharmatools.ai,https://pharmatools.aiCORS allowlist for /tighten
PER_IP_PER_MIN / PER_IP_PER_DAY4 / 25Tightener per-client limits
GLOBAL_PER_DAY1500Tightener daily cap across all clients
MAX_INPUT_CHARS1500Tightener input cap
PUBLIC_PER_IP_PER_MIN120Limit for /mcp and /api/*
DOCS_URLhttps://www.pharmatools.ai/mcp#footprintWhere / redirects
PROXY_ENTRIES1How many entries your hosting proxy adds to the right of X-Forwarded-For (Railway: 1). Rate limits use the entry just before them; anything further left is ignored

Also in this repo: the prompt tightener

POST /tighten powers the "Make your first prompt the only one" tool on the calculator page. It sends a draft prompt to Claude Haiku, which rewrites it to get a usable answer first time, filling gaps with [placeholders] rather than invented facts. The page then shows what the rewrite itself cost in water against the follow-ups it should save. Unlike the footprint tools it calls a model, so it's locked down: pharmatools.ai-only CORS, a 1,500-character input cap, per-IP and daily caps, forced tool output and no prompt logging. The page embed is in web/prompt-tightener-embed.html.

POST /read-claim backs the headline checker on the same page. The page reads well-known claims and simple figures itself, in the browser. Only when it can't, and the visitor chooses to, it sends the claim here. The model just extracts what the claim states (amount, unit, what it's per), and the page explains it with fixed rules. It has the same protections as /tighten.

Development

bash
cd serverpip install -r requirements.txt -r requirements-dev.txtMOCK=1 python -m pytest -q      # tests, including parity with the calculator pageruff check ..                   # lint

CI runs lint and tests on Python 3.10 to 3.13, then starts the server and drives it end to end with the MCP client example. Pushing a v* tag publishes a GitHub release with notes taken from the changelog.

server/  footprint.py        constants, methodology and arithmetic (single source of truth)  mcp_tools.py        the four MCP tools  main.py             ASGI app: /mcp, /api/*, /tighten, /read-claim, CORS and rate limits  test_footprint.py   parity, validation and HTTP testsexamples/             MCP client, JS and curl examples, captured outputsweb/                  calculator-page embed for the tightenerserver.json           MCP Registry entry

Privacy

The hosted server keeps no record of what you ask. Its logs contain the name of the tool or endpoint called, nothing else: no inputs, prompts or IP addresses. Client IP addresses are held in memory only to enforce rate limits. They are never logged or written to disk, and are discarded when the server restarts. There's no database and no account. The server runs on Railway, and nothing is shared with anyone else. Full policy: pharmatools.ai/privacy-policy. Questions: [email protected].

Contributing

Issues and pull requests are welcome, particularly better sources. Read CONTRIBUTING.md first: changes to the figures follow a short methodology process so the server and the calculator page stay in step. Security issues go through SECURITY.md, not public issues.

Embed the calculator on your site

One line, no account or key. It works on any site that accepts a script tag, including WordPress, Webflow, Squarespace and Ghost.

html
<script src="https://footprint.pharmatools.ai/widget.js" data-theme="auto" data-prompts="25" data-mix="text" async></script>

Options: data-theme (light, dark, auto), data-accent (a hex colour such as 0d7377), data-prompts (1–200), data-mix (text, mixed, intensive) and data-basis (comprehensive, onsite). Where scripts aren't allowed, use the iframe directly:

html
<iframe src="https://footprint.pharmatools.ai/widget?theme=auto&prompts=25" title="AI water and energy calculator" width="100%" height="560" style="border:0;max-width:640px" loading="lazy"></iframe>

The widget uses the same figures and methodology version as the API, computes everything in the visitor's browser and sets no cookies. The calculator page has a builder with a live preview.

Citing

Lamb, N. (2026). An energy-first method for estimating the water and energy footprint of AI use (methodology 2026-10) [Preprint]. Zenodo. https://doi.org/10.5281/zenodo.23417340

GitHub's Cite this repository button gives the software citation from CITATION.cff.

License

MIT © PharmaTools.AI

来源：README.md，提交 22449b1

工具

4

estimate_ai_footprint

Estimate AI water & energy footprint

Estimate the water (mL) and energy (Wh) used by chat-style AI prompts (ChatGPT, Claude, Gemini etc.). queries_per_day: prompts per day. usage: 'simple' (text chat, ~0.34 Wh/prompt), 'mixed' (~1 Wh), 'intensive' (image generation / deep reasoning, ~3 Wh). boundary: 'onsite' (data-centre cooling only, as vendors report) or 'comprehensive' (adds water used to generate the electricity – the wider boundary most researchers use). days: number of days to total over (e.g. 250 workdays, 365). Returns per-prompt, per-day and total figures with everyday equivalents, assumptions and a source link. For agentic/coding sessions use estimate_session_footprint instead.

输入参数daysusageboundaryqueries_per_day必填

get_methodology

AI water footprint methodology and sources

Return the per-prompt energy and water figures, accounting boundaries, sources, limitations, a citation line, and the reasons published AI water estimates differ by ~100x (0.3 mL to 50 mL per prompt). Use it to explain or check a published AI water or energy figure.

无需输入参数。

compare_water_use

Put an amount of water in everyday context

Convert a volume of water (mL) into everyday comparisons: teaspoons, 500 mL bottles, shower time, and lifecycle items (A4 sheet, almond, cup of tea, beef burger), plus the number of typical AI text prompts it equals. Includes the boundary caveat that lifecycle footprints are not like-for-like.

输入参数water_ml必填

estimate_session_footprint

Estimate an AI session's footprint from token counts

Estimate the water and energy of an AI session (e.g. an agent or coding-assistant run) from its token usage. Pass the SUM across all model calls: input_tokens (uncached prompt tokens), output_tokens (including any reasoning/thinking tokens) and cached_input_tokens (prompt-cache reads). model_class: 'small' (Haiku/mini/Flash-class), 'frontier' or 'reasoning'. Returns a central estimate and a 0.3x–3x range – this is an order-of-magnitude estimate calibrated to published per-prompt figures, not a measurement.

输入参数boundarymodel_classinput_tokens必填output_tokens必填cached_input_tokens

版本历史

3
  1. v1.0.4最新Oct 13, 2026
  2. v1.0.3Oct 13, 2026
  3. v1.0.0Oct 11, 2026

评分

已满足适用检查项的 100%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通必需25 分
  • 已声明认证方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分