usage-planner — Claude Code MCP server: install and guide
usage-planner is a Claude Code MCP server that plans OpenAI Codex weekly quota and forecasts quota resets. It builds a two-week timeline across five usage strategies.
MIT ★ 5 updated 2026-10-29
claude mcp add usage-planner -- npx -y usage-plannerWhat usage-planner does
usage-planner tracks remaining OpenAI Codex quotas directly from a signed-in local Codex session. The server generates a day-by-day timeline spanning two weeks, marking daily usage, scheduled resets, and remaining capacity.
It projects unscheduled reset probability for the next 48 hours using historical reset data, factoring them in only when the likelihood reaches at least 60%. Five planning strategies help allocate tokens across weekdays or hold reserves for service outages.
Running the MCP server requires Node.js 20+ and a logged-in Codex CLI on the host machine. The server reads balance locally and never triggers resets or spends quota on its own.
What it helps with
- forecast OpenAI Codex quota run-out dates based on current pace
- estimate the likelihood of an extra quota reset within 48 hours
- schedule banked reset redemptions across a two-week window
- distribute quota across weekdays or weekend-focused schedules
Example prompts for the agent
- Show the two-week quota forecast for Codex
- Check when my Codex weekly limit runs out at the current pace
- Plan my quota using the weekdays-only strategy
How to install usage-planner
Platform CLI
claude mcp add usage-planner -- npx -y usage-plannerPlatform CLI
codex mcp add usage-planner -- npx -y usage-plannerConfig file
{
"mcpServers": {
"usage-planner": {
"command": "npx",
"args": [
"-y",
"usage-planner"
]
}
}
}Config file
{
"servers": {
"usage-planner": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"usage-planner"
]
}
}
}Platform CLI
gemini mcp add usage-planner npx -y usage-plannerStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about usage-planner
How to install usage-planner in Claude Code?
Run claude mcp add usage-planner -- npx -y usage-planner to register the server.
What does usage-planner do?
It reads local Codex usage data, maps a two-week consumption schedule, and calculates the probability of automatic quota resets.
What is required to run usage-planner?
The host system needs Node.js 20 or higher alongside a signed-in Codex CLI instance to inspect local quota balances.