Skip to main content
Glama
Sign In
soif-mcp

soif-mcp

by Unchained-Labs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

soif-mcp šŸ’§šŸ”Œ

M8ven Score

MCP server for soif ā€” lets any MCP client (Claude Code, Claude Desktop, Cursor, agent frameworks) estimate the water footprint of LLM usage and route models by water cost.

All figures are millilitres of freshwater consumed, returned as {low, mid, high} scenario ranges with explicit assumptions ā€” see the methodology.

Tools

Tool

What it does

estimate_water

Water for one call from model + tokens (or prompt text), incl. reasoning effort, provider/region overrides

estimate_from_usage

The accurate path: feed a real OpenAI/Anthropic usage object

compare_models

Rank candidate models least- to most-thirsty for a workload

pick_low_water_model

Route a step: least-thirsty model above a capability floor (min_tier)

list_known_models

Registry of recognised models with tier/provider defaults

Plus a soif://methodology resource summarising how estimates are computed.

Related MCP server: Lean Reader

Install & connect

Requires Python ā‰„ 3.10. Once released to PyPI, uvx soif-mcp just works; from git today:

uv tool install "soif-mcp @ git+https://github.com/Unchained-Labs/soif-mcp.git"
# or: pipx install "soif-mcp @ git+https://github.com/Unchained-Labs/soif-mcp.git"

Claude Code

claude mcp add soif -- soif-mcp
# or without installing first:
claude mcp add soif -- uvx --from "git+https://github.com/Unchained-Labs/soif-mcp.git" soif-mcp

Claude Desktop / any JSON-config client (claude_desktop_config.json):

{
  "mcpServers": {
    "soif": { "command": "soif-mcp" }
  }
}

Cursor (.cursor/mcp.json): same shape as above.

The server speaks stdio (the standard transport for local servers); no network access, no credentials, no state.

Example prompts once connected

  • "How much water did that last answer cost? Here's the usage object: ā€¦"

  • "Compare gpt-4o, gpt-4o-mini and gemini-2.5-flash on water for a 2k-in/500-out workload."

  • "Pick the least-thirsty model of these that's at least medium tier."

Publishing / marketplaces

Registries worth listing this server in (in rough order of impact):

  1. Official MCP Registry ā€” the canonical registry (publish via mcp-publisher CLI with a server.json); most clients and sub-registries sync from it.

  2. GitHub MCP Registry ā€” surfaced directly in GitHub and VS Code/Copilot.

  3. Smithery ā€” largest community registry; hosted install pages and one-line client setup.

  4. PulseMCP and Glama ā€” widely-browsed directories, auto-index from the official registry/GitHub.

  5. mcp.so ā€” community directory, simple PR/submit flow.

  6. Docker MCP Catalog ā€” if a container image is published; used by Docker Desktop's MCP Toolkit.

  7. Cline MCP Marketplace ā€” in-editor marketplace for the Cline agent (submit via their GitHub repo).

  8. PyPI itself ā€” uvx soif-mcp is the install path most registries point at, so the PyPI release (see release.yml) underpins all of the above.

Development

pip install "soif-llm @ git+https://github.com/Unchained-Labs/soif.git"
pip install -e ".[dev]"
pytest && ruff check .

License

MIT

Available Tools

5 tools
compare_modelsB

Rank candidate models by mid-scenario water use for a workload.

Returns models sorted least- to most-thirsty, each with its tier and water range in mL. min_tier ("nano"|"small"|"medium"|"large"| "frontier") filters out models below a capability floor.

Inputs: models (required), min_tier, input_tokens, output_tokens. Returns: result

estimate_from_usageA

Estimate water (mL) from a real API usage object ā€” the accurate path.

usage accepts OpenAI Chat Completions shape (prompt_tokens / completion_tokens, with completion_tokens_details.reasoning_tokens and prompt_tokens_details.cached_tokens), OpenAI Responses shape, or Anthropic Messages shape (input_tokens / output_tokens, cache_read_input_tokens, cache_creation_input_tokens). Reasoning and cached tokens are handled without double counting.

Inputs: model (required), usage (required), region, include_embodied. Returns: object

estimate_waterA

Estimate the freshwater consumed (mL) by one LLM call.

Provide real token counts when known; otherwise pass prompt text (tokens are approximated and output defaults to a typical 500 tokens). reasoning_effort ("none"|"low"|"medium"|"high") models thinking tokens when actual usage is unknown. provider ("aws"|"azure"|"gcp"|"average") and region ("world"|"us"|"eu"|"france"|"nordics"|"asia"|"renewable") override the hosting profile. Set include_embodied=false for operational water only. Returns water/energy breakdowns as {low, mid, high} ranges plus a human summary and the assumptions made.

Inputs: model (required), prompt, region, provider, +6 more. Returns: object

list_known_modelsA

List models soif recognises, with their size tier and default hosting.

Unknown models still work everywhere (they fall back to the "large" tier with an explicit assumption), but known models get calibrated tier/provider/region defaults.

Inputs: no named parameters. Returns: result

pick_low_water_modelA

Pick the least-thirsty candidate model that meets a capability floor.

Use in agent graphs to route each step: set min_tier to the minimum capability the step needs, and the tool returns the lowest-water model among the candidates plus what it saves vs. the thirstiest candidate.

Inputs: candidates (required), min_tier, input_tokens, output_tokens. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogā€¦

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.9/5.0

    Scored across 5 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: estimate_from_usage handles API usage objects, estimate_water handles manual/approximate inputs, compare_models ranks, and pick_low_water_model selects. The only mild ambiguity is between compare_models and pick_low_water_model, which both operate on candidate models and min_tier, though one returns a ranked list and the other returns a single pick.

    Naming Consistency4/5

    All tool names follow a descriptive snake_case verb-first pattern: estimate_*, compare_*, pick_*, list_*. The only slight inconsistency is estimate_from_usage using a prepositional phrase rather than the simple verb_noun shape used by the others.

    Tool Count5/5

    Five tools is well-scoped for this domain. Each tool earns its place: estimation from usage objects, estimation from manual inputs, model comparison, low-water model selection, and known-model metadata.

    Completeness5/5

    The toolkit covers the full workflow: lookup known models, estimate water for a single call via either real usage or approximate inputs, compare models for a workload, and pick the least-thirsty model for routing. There are no obvious dead ends or missing core operations for this focused purpose.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers