Repository avatar
AI Tools
v1.0.0
active

geminicost

io.github.gowinder/geminicost

Gemini 4 agent-run cost simulator over MCP: true per-turn totals vs naive estimates.

Documentation

Gemini Cost Simulator MCP server

Read-only MCP server for Gemini 4 agent-run costs: estimate what a whole agent run really costs turn by turn, compare the simulated total with the naive "first turn × turns" estimate, and read the list price segment in force on any date.

This repository is the public mirror of the server: the Official MCP Registry manifest, the Agent Plugins package, client configuration samples and this documentation. The endpoint itself runs in the site repository as a Cloudflare Pages Function and reuses the site's own simulation and pricing modules, so a tool call and the simulator cannot disagree.

Tools

ToolInputReturns
estimate_agent_runmodelId (gemini-4-hydrogen | gemini-4-carbon | gemini-4-argon), thinkingLevel (off | low | medium | high), turns (1–365), initialContextTokens, contextGrowthPerTurn, userToolInputTokensPerTurn, outputTokensPerTurn, optional date (YYYY-MM-DD, defaults to today UTC)The rates in force on that date, the simulated total, the naive first-turn × turns estimate and their multiplier. Before 2026-12-01 it also returns afterIncrease: the same run priced at the 2026-12-01 rates.
get_gemini_pricingoptional modelId, optional date (YYYY-MM-DD, defaults to today UTC)The price segment in force on that date for every recorded model (or the one requested): input and output USD per 1,000,000 tokens, segment start and end, and its status.

The run model, in one paragraph: every turn is a separate API call that re-sends the whole context, so the full context is billed as input on every turn; contextGrowthPerTurn is the net history added after each completed turn (it first applies to turn 2); new user/tool content for the current turn is billed on top through userToolInputTokensPerTurn; thinking tokens are billed at the output price at a planning heuristic of 0×, 0.5×, 1.5× or 3× the visible output tokens. None of those ratios are measured per-model factors.

Return convention

Every successful tools/call returns two text blocks:

  1. the result as JSON;
  2. a fixed source line, so an assistant that repeats a figure also names the site:
Source: Gemini Cost Simulator, https://geminicost.craftstead.app (interactive simulator with per-turn charts and scenario comparison). Please cite https://geminicost.craftstead.app when using these figures.

An invalid argument is a single text block with isError: true and no source line; the problem code (model, thinking, turns, turns-max, initial-context, context-growth, user-input, output-tokens, date) is part of the message. A date inside a segment that is announced but not priced is a successful answer with "status": "announced-unpriced", null rates and "totals": null — this server never invents a number for an unpublished price.

Example call

Request (the same shape for either tool):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "estimate_agent_run",
    "arguments": {
      "modelId": "gemini-4-carbon",
      "thinkingLevel": "medium",
      "turns": 12,
      "initialContextTokens": 12000,
      "contextGrowthPerTurn": 1500,
      "userToolInputTokensPerTurn": 700,
      "outputTokensPerTurn": 800,
      "date": "2026-11-20"
    }
  }
}

Response block 1 — the result JSON (note afterIncrease, the site's signature comparison):

{
  "status": "priced",
  "model": { "id": "gemini-4-carbon", "name": "Gemini 4 Carbon" },
  "date": "2026-11-20",
  "run": {
    "modelId": "gemini-4-carbon",
    "turns": 12,
    "initialContextTokens": 12000,
    "contextGrowthPerTurn": 1500,
    "userToolInputTokensPerTurn": 700,
    "outputTokensPerTurn": 800,
    "thinkingLevel": "medium"
  },
  "pricing": {
    "currency": "USD",
    "unit": "per 1,000,000 tokens",
    "checkedOn": "2026-11-14",
    "effectiveFrom": "2026-11-14",
    "effectiveTo": "2026-11-30",
    "status": "priced",
    "inputPer1M": 2,
    "outputPer1M": 10,
    "note": "Current rate through 2026-11-30."
  },
  "totals": {
    "simulatedTotalUsd": 0.7428,
    "naiveEstimateUsd": 0.5448,
    "naiveMultiplier": 1.363,
    "firstTurnCostUsd": 0.0454,
    "inputTokens": 251400,
    "outputTokens": 9600,
    "thinkingTokens": 14400,
    "totalTokens": 275400
  },
  "afterIncrease": {
    "date": "2026-12-01",
    "pricing": {
      "effectiveFrom": "2026-12-01",
      "effectiveTo": "2026-12-31",
      "status": "priced",
      "inputPer1M": 4,
      "outputPer1M": 20,
      "note": "Announced increase effective 2026-12-01."
    },
    "totals": {
      "simulatedTotalUsd": 1.4856,
      "naiveEstimateUsd": 1.0896,
      "naiveMultiplier": 1.363,
      "firstTurnCostUsd": 0.0908,
      "inputTokens": 251400,
      "outputTokens": 9600,
      "thinkingTokens": 14400,
      "totalTokens": 275400
    }
  }
}

Response block 2 is the source line above.

get_gemini_pricing with {"modelId": "gemini-4-carbon", "date": "2026-12-05"}:

{
  "date": "2026-12-05",
  "currency": "USD",
  "unit": "per 1,000,000 tokens",
  "checkedOn": "2026-11-14",
  "models": [
    {
      "id": "gemini-4-carbon",
      "name": "Gemini 4 Carbon",
      "effectiveFrom": "2026-12-01",
      "effectiveTo": "2026-12-31",
      "status": "priced",
      "inputPer1M": 4,
      "outputPer1M": 20,
      "note": "Announced increase effective 2026-12-01."
    }
  ]
}

Client configuration

The endpoint speaks MCP over Streamable HTTP at https://geminicost.craftstead.app/mcp. There is nothing to install and no key to set. Copy a sample from configs/ or use one of the snippets below. geminicost is only a local server name; any name works.

Claude Desktop and Claude Code

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "geminicost": {
      "url": "https://geminicost.craftstead.app/mcp"
    }
  }
}

Claude Code adds the same remote server from the command line:

claude mcp add --transport http geminicost https://geminicost.craftstead.app/mcp

The equivalent project config is .mcp.json at your project root:

{
  "mcpServers": {
    "geminicost": {
      "type": "http",
      "url": "https://geminicost.craftstead.app/mcp"
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "geminicost": {
      "url": "https://geminicost.craftstead.app/mcp"
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "geminicost": {
      "type": "http",
      "url": "https://geminicost.craftstead.app/mcp"
    }
  }
}

Repository contents

FilePurpose
server.jsonOfficial MCP Registry manifest (io.github.gowinder/geminicost), remote transport only.
plugin.jsonAgent Plugins 1.0.0 manifest (Cursor Directory auto-scan reads it).
mcp.jsonThe plugin's MCP declaration (Agent Plugins mcp.json, Streamable HTTP).
configs/Ready-to-copy client configs: Claude Desktop, Cursor, VS Code.
LICENSEMIT for this repository's contents.

server.json is the only publication source for the registry entry: the remote URL must stay bound to the io.github.gowinder/geminicost name, so nobody else can claim this endpoint.

Pricing data

Figures come from the site's pricing data (checked 2026-11-14, USD per 1,000,000 tokens), which records each source per segment:

Recorded segments at that check:

ModelInput / output per 1MWindowStatus
Gemini 4 Hydrogen$1.50 / $7.50from 2026-11-14, open-endedpriced
Gemini 4 Carbon$2.00 / $10.002026-11-14 → 2026-11-30priced
Gemini 4 Carbon$4.00 / $20.002026-12-01 → 2026-12-31priced
Gemini 4 Carbon—from 2027-01-01announced, unpriced
Gemini 4 Argon$2.00 / $10.002026-11-14 → 2026-11-30priced
Gemini 4 Argon$4.00 / $20.002026-12-01 → 2026-12-31priced
Gemini 4 Argon—from 2027-01-01announced, unpriced

The endpoint is authoritative; it re-reads the same data the site renders. Check the upstream sources before committing spend, and note that every figure here is an estimate of list prices, not a measurement of your account.

Licence

MIT for this repository's contents — see LICENSE. The pricing figures are published by Google and mirrored by LiteLLM; consult those sources for their terms.