{"id":51290234,"url":"https://github.com/tylergibbs1/tokenomics","last_synced_at":"2026-06-30T09:32:03.421Z","repository":{"id":367363525,"uuid":"1280479697","full_name":"tylergibbs1/tokenomics","owner":"tylergibbs1","description":"Fresh, live LLM pricing for AI agents — CLI + MCP server. 400+ models from the OpenRouter Models API, normalized to USD per 1M tokens.","archived":false,"fork":false,"pushed_at":"2026-06-25T16:22:38.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T18:14:25.508Z","etag":null,"topics":["ai-agents","claude","cli","effect-ts","llm","llm-pricing","mcp","model-context-protocol","openrouter","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tylergibbs1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-25T16:15:16.000Z","updated_at":"2026-06-25T16:22:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tylergibbs1/tokenomics","commit_stats":null,"previous_names":["tylergibbs1/tokenomics"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tylergibbs1/tokenomics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tylergibbs1%2Ftokenomics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tylergibbs1%2Ftokenomics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tylergibbs1%2Ftokenomics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tylergibbs1%2Ftokenomics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tylergibbs1","download_url":"https://codeload.github.com/tylergibbs1/tokenomics/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tylergibbs1%2Ftokenomics/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34961544,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude","cli","effect-ts","llm","llm-pricing","mcp","model-context-protocol","openrouter","typescript"],"created_at":"2026-06-30T09:32:03.290Z","updated_at":"2026-06-30T09:32:03.402Z","avatar_url":"https://github.com/tylergibbs1.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 💸 tokenomics\n\n### Fresh, live LLM pricing for AI agents — as a CLI **and** an MCP server.\n\nNo scraping. No database. No API keys. Every call returns current pricing for **thousands of models\nacross 140+ providers**, straight from the [models.dev catalog](https://models.dev)\nand normalized to **USD per 1M tokens**.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js\u0026logoColor=white)](https://nodejs.org)\n[![Built with Effect](https://img.shields.io/badge/built%20with-Effect-5c5cff?logo=typescript\u0026logoColor=white)](https://effect.website)\n[![MCP](https://img.shields.io/badge/MCP-compatible-7c3aed)](https://modelcontextprotocol.io)\n[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://prettier.io)\n[![linted with oxlint](https://img.shields.io/badge/linted_with-oxlint-cc9f1f)](https://oxc.rs)\n\n\u003c/div\u003e\n\n---\n\n## Why\n\nLLMs in agents need to reason about cost — _which model is cheapest for this job, what will this prompt cost, is the cheaper model worth it?_ — but pricing data goes stale the moment you hardcode it. **tokenomics** gives an agent a single, always-fresh source of truth and does the per-million math so the agent never fumbles a `1K` vs `1M` conversion.\n\nIt's built the way Anthropic recommends agent tools should be built: a small set of **deep, workflow-level tools** (not a CRUD wrapper), JSON-by-default output, runtime schema introspection, input hardening, and field masks to keep responses small.\n\n## Features\n\n|                               |                                                                                               |\n| ----------------------------- | --------------------------------------------------------------------------------------------- |\n| 🔴 **Always live**            | Fetches models.dev on every call — data is fresh by construction. No DB to go stale.          |\n| 🔌 **Two surfaces, one core** | The same engine powers an agent-friendly CLI and an MCP server. Identical behavior.           |\n| 🧮 **Does the math**          | `estimate` and `compare` compute real USD cost from token counts and request volume.          |\n| 🤖 **Agent-first**            | JSON when piped, field masks, NDJSON, machine-readable errors, schema introspection.          |\n| 🧰 **MCP best-practices**     | Rich server instructions, structured tool descriptions, graceful timeouts, soft \"not found\".  |\n| 🛡️ **Hardened input**         | Rejects control chars, path traversal, and embedded query params at the boundary.             |\n| ⚡ **Typed \u0026 tested**         | Built on [Effect](https://effect.website) with tagged errors; Prettier + oxlint + unit tests. |\n\n## Quickstart\n\n**One-command install** (clone, build, and put `tokenomics` + `tokenomics-mcp` on your PATH):\n\n```bash\ngit clone https://github.com/tylergibbs1/tokenomics.git \u0026\u0026 cd tokenomics \u0026\u0026 npm install \u0026\u0026 npm run build \u0026\u0026 npm link\n```\n\n\u003cdetails\u003e\n\u003csummary\u003ePrefer it step by step?\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/tylergibbs1/tokenomics.git\ncd tokenomics\nnpm install\nnpm run build\nnpm link        # optional: puts the binaries on your PATH\n```\n\n\u003c/details\u003e\n\nRequires **Node 20+**. No API key needed — the models.dev catalog is public.\n\n## CLI\n\nOutput is **JSON when piped** (agent-friendly) and a **table at a terminal**. Override with `-o json|ndjson|table`.\n\n```bash\n# 🔎 Search + filter, and trim the response with a field mask\ntokenomics search \"claude\" --max-input 5 --min-context 200000 \\\n  --fields model_id,pricing,context_window\n\n# 📄 One model's full pricing + provenance\ntokenomics get openai/gpt-4o\n\n# 🧮 Cost of a workload (raw token counts) × N requests\ntokenomics estimate openai/gpt-4o --input-tokens 1000000 --output-tokens 200000 --requests 10\n\n# ⚖️  Rank candidates by total cost for the same workload (cheapest first)\ntokenomics compare --models openai/gpt-4o,google/gemini-2.5-flash \\\n  --input-tokens 1000000 --output-tokens 500000\n\n# 🏷️  Providers present in the live data, with counts\ntokenomics providers\n\n# 📐 Runtime schema introspection — the CLI documents itself\ntokenomics schema estimate\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eExample output\u003c/b\u003e — \u003ccode\u003etokenomics get openai/gpt-4o\u003c/code\u003e\u003c/summary\u003e\n\n```json\n{\n  \"provider\": \"openai\",\n  \"model_id\": \"openai/gpt-4o\",\n  \"display_name\": \"GPT-4o\",\n  \"modality\": \"multimodal\",\n  \"pricing\": {\n    \"input_per_mtok\": 2.5,\n    \"output_per_mtok\": 10,\n    \"cached_input_per_mtok\": 1.25,\n    \"cache_write_per_mtok\": null\n  },\n  \"context_window\": 128000,\n  \"max_output_tokens\": 16384,\n  \"unit\": \"USD per 1M tokens\",\n  \"currency\": \"USD\",\n  \"source_url\": \"https://models.dev\",\n  \"fetched_at\": \"2026-06-25T16:00:21.174Z\",\n  \"source\": \"models.dev\"\n}\n```\n\n\u003c/details\u003e\n\nErrors are machine-readable on stderr with a stable `code`, an actionable `suggestion`, and a non-zero exit:\n\n```json\n{\n  \"error\": true,\n  \"code\": \"MODEL_NOT_FOUND\",\n  \"message\": \"No model matching 'gtp-4o'.\",\n  \"suggestion\": \"Use 'tokenomics search' to list available models.\",\n  \"details\": { \"suggestions\": [] }\n}\n```\n\n## MCP server\n\nFour **read-only, workflow-level** tools — each bundles the live fetch, model matching, and cost math so an agent needs one call, not three.\n\n| Tool                | Use it for                                                               |\n| ------------------- | ------------------------------------------------------------------------ |\n| `search_models`     | Discover / shortlist models by price, modality, or context window        |\n| `get_model_pricing` | One known model's full pricing (a miss returns candidates, not an error) |\n| `estimate_cost`     | The USD cost of a workload on a single model                             |\n| `compare_models`    | Rank candidate models by total cost for the same workload                |\n\n### Add to Claude Code\n\n```bash\nclaude mcp add tokenomics -- node /absolute/path/to/tokenomics/dist/bin/tokenomics-mcp.js\n```\n\n### Add to Claude Desktop\n\n```jsonc\n// claude_desktop_config.json\n{\n  \"mcpServers\": {\n    \"tokenomics\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/tokenomics/dist/bin/tokenomics-mcp.js\"],\n    },\n  },\n}\n```\n\nThe server ships rich `instructions` (purpose, the units convention, when to use which tool) that clients surface to the model automatically.\n\n## Units (the one thing to remember)\n\n- **Every price is USD per 1,000,000 tokens.** `2.5` means $2.50 per 1M tokens.\n- `estimate` / `compare` take **raw token counts** (e.g. `1000000`), not millions.\n- `output_per_mtok: null` ⇒ non-generative model (embeddings/rerankers); output tokens cost $0.\n- Model ids are `provider/model`, where `provider` is the **serving** provider, e.g. `openai/gpt-4o`, `anthropic/claude-sonnet-4-5`. The same model is often served by several providers at different prices — compare across them by id.\n\n## How it works\n\n```mermaid\nflowchart LR\n    MD[models.dev\u003cbr/\u003e/api.json] --\u003e|live fetch + timeout| MAP[map → ModelPricing\u003cbr/\u003eUSD per 1M tokens]\n    MAP --\u003e Q{query}\n    Q --\u003e S[search]\n    Q --\u003e G[get]\n    Q --\u003e E[estimate]\n    Q --\u003e C[compare]\n    S \u0026 G \u0026 E \u0026 C --\u003e CLI[CLI]\n    S \u0026 G \u0026 E \u0026 C --\u003e MCP[MCP server]\n```\n\nA single `ModelsDev` Effect service fetches and normalizes the catalog — flattening every provider's models into one list of `(provider, model)` records — cached in-process for `TOKENOMICS_CACHE_TTL_SECONDS` (default 60s). Both the CLI and the MCP server call one shared operations layer, so they behave identically and share typed, tagged errors.\n\n## Configuration\n\nAll optional — sensible defaults work out of the box.\n\n| Variable                       | Default                       | Description                                                                       |\n| ------------------------------ | ----------------------------- | --------------------------------------------------------------------------------- |\n| `MODELS_DEV_API_URL`           | `https://models.dev/api.json` | Source endpoint (override to proxy)                                               |\n| `TOKENOMICS_CACHE_TTL_SECONDS` | `60`                          | In-process reuse window; `0` = fetch fresh every call                             |\n| `TOKENOMICS_FETCH_TIMEOUT_MS`  | `15000`                       | Hard timeout so a hung network fails fast                                         |\n| `TOKENOMICS_STRICT_LOOKUP`     | `false`                       | `1` makes a `get_model_pricing` miss a hard error instead of returning candidates |\n\n## Development\n\n```bash\nnpm run dev:cli -- search \"gpt\"   # run the CLI from source (tsx)\nnpm run dev:mcp                    # run the MCP server from source\nnpm run check                     # prettier --check + oxlint + tsc --noEmit\nnpm test                          # unit tests for the pricing math\n```\n\n## Roadmap\n\n- [ ] Additional pricing sources (direct provider pages) as sibling Effect services, merged transparently\n- [ ] Token counting from raw text/files so `estimate` can price an actual prompt\n- [ ] Filter/surface model metadata from models.dev (reasoning, tool-calling, attachments)\n- [ ] Publish to npm + `.mcpb` bundle for one-click Desktop install\n\n## License\n\n[MIT](LICENSE) © Tyler Gibbs\n\n\u003cdiv align=\"center\"\u003e\n\u003csub\u003eBuilt for agents, with \u003ca href=\"https://effect.website\"\u003eEffect\u003c/a\u003e + the \u003ca href=\"https://modelcontextprotocol.io\"\u003eModel Context Protocol\u003c/a\u003e.\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftylergibbs1%2Ftokenomics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftylergibbs1%2Ftokenomics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftylergibbs1%2Ftokenomics/lists"}