
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.
- Endpoint:
https://geminicost.craftstead.app/mcp(MCP over Streamable HTTP, JSON-RPC POST) - Authentication: none. No key, no account, no cookies.
- Mode: read-only, stateless, softly rate limited per client IP.
- Website: https://geminicost.craftstead.app — interactive simulator with per-turn charts and scenario comparison: https://geminicost.craftstead.app/mcp-server/
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
| Tool | Input | Returns |
|---|---|---|
estimate_agent_run | modelId (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_pricing | optional 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:
- the result as JSON;
- 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
| File | Purpose |
|---|---|
server.json | Official MCP Registry manifest (io.github.gowinder/geminicost), remote transport only. |
plugin.json | Agent Plugins 1.0.0 manifest (Cursor Directory auto-scan reads it). |
mcp.json | The plugin's MCP declaration (Agent Plugins mcp.json, Streamable HTTP). |
configs/ | Ready-to-copy client configs: Claude Desktop, Cursor, VS Code. |
LICENSE | MIT 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:
- LiteLLM — Gemini 4 model pricing pages — https://models.litellm.ai/
- Google — Gemini API pricing (official) — https://ai.google.dev/gemini-api/docs/pricing
Recorded segments at that check:
| Model | Input / output per 1M | Window | Status |
|---|---|---|---|
| Gemini 4 Hydrogen | $1.50 / $7.50 | from 2026-11-14, open-ended | priced |
| Gemini 4 Carbon | $2.00 / $10.00 | 2026-11-14 → 2026-11-30 | priced |
| Gemini 4 Carbon | $4.00 / $20.00 | 2026-12-01 → 2026-12-31 | priced |
| Gemini 4 Carbon | — | from 2027-01-01 | announced, unpriced |
| Gemini 4 Argon | $2.00 / $10.00 | 2026-11-14 → 2026-11-30 | priced |
| Gemini 4 Argon | $4.00 / $20.00 | 2026-12-01 → 2026-12-31 | priced |
| Gemini 4 Argon | — | from 2027-01-01 | announced, 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.
No installation packages available.