Skip to main content
Glama
AlonTsur1601

CountdownMCP

by AlonTsur1601
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

CountdownMCP

CI M8ven Score

CountdownMCP is a local, read-only MCP server that gives Codex and Claude Code a plan-aware view of its remaining usage and helps it choose work that fits the current usage window.

It reports a percentage in the context of the actual plan (plus, pro, and other Codex plan types). It does not invent a token allowance or pretend that the same percentage means the same capacity across plans.

CountdownMCP complements TodoMCP, but both servers remain fully independent and useful on their own.

Codex should skip CountdownMCP for small, self-contained, low-risk tasks that can reasonably finish in one short turn. It should check usage once before work expected to take more than 10 minutes, require at least three meaningful execution steps, involve repeated implementation-and-test cycles, or be explicitly described as continuing across multiple substantial prompts.

What it does

  • Reads live ChatGPT/Codex rate-limit data through the local Codex app-server.

  • Under Claude Code, reads live usage from the same endpoint the /status command uses, via the OAuth token Claude Code already stores locally after claude login. This mirrors the approach used by community tools such as ccusage, since Claude Code has no public CLI command or app-server RPC for this yet (tracked upstream: anthropics/claude-code#44328, #32796). The token is only read, never written back.

  • Reports plan, used and remaining percentages, all returned windows, reset time, credits, and limit state.

  • Compares the five-hour and weekly windows by estimated remaining capacity rather than treating equal percentages as equal quota. Based on measurements after the August 2026 restoration of the Plus five-hour limit, a full five-hour allowance is estimated as 16% of the weekly allowance (about 6.25 full five-hour allowances per week).

  • Falls back to the latest local Codex rate-limit metadata when app-server access is unavailable. Fallback results are explicitly marked with their source and staleness. There is no equivalent local fallback for Claude Code yet, since Claude Code does not write a comparable local rate-limit snapshot.

  • Advises which ready tasks to run in normal, guarded, critical, and exhausted usage states.

  • Keeps an active, continuation-safe task eligible even at 0% remaining, because an already-running Codex turn can often continue without a new user message.

  • Uses STDIO only: no port, HTTP server, account token, or direct modification of another MCP server.

Related MCP server: agenticscope

Requirements

  • Node.js 18 or newer

  • For Codex: the Codex CLI available as codex and signed in to ChatGPT

  • For Claude Code: signed in once via claude login (or the desktop app), so ~/.claude/.credentials.json holds a valid access token

Install

Clone the repository and run the installer:

git clone https://github.com/AlonTsur1601/CountdownMCP.git
Set-Location CountdownMCP
node install.mjs

The installer builds and tests the project first. It then installs a stable runtime under CODEX_HOME/mcp/countdown-mcp (normally ~/.codex/mcp/countdown-mcp) and updates only the countdown_mcp entry through the Codex CLI. Restart Codex after installation.

The installer preserves every other MCP entry. If replacing the CountdownMCP entry fails, it restores the prior Codex configuration and prior installed CountdownMCP runtime.

An installed copy is a local snapshot. New Git commits and GitHub Releases do not update it automatically. To update an existing clone, pull the newer source and rerun the installer:

Set-Location CountdownMCP
git pull --ff-only
node install.mjs

Restart Codex after installing or updating.

Tools

countdown_get_usage

No input. Returns structured data similar to:

{
  "planType": "plus",
  "usedPercent": 31,
  "remainingPercent": 69,
  "effectiveLimitId": "codex",
  "source": "app_server",
  "stale": false
}

Credits are reported separately from the plan percentage. source is app_server or session_fallback for Codex, and claude_oauth for Claude Code.

countdown_advise_work

Accepts the TodoMCP WorkCandidate v1 contract. Unknown fields are ignored for forward compatibility:

{
  "currentTaskId": "task-1",
  "tasks": [
    {
      "id": "task-1",
      "title": "Run integration tests",
      "priority": 5,
      "estimatedMinutes": 20,
      "dependenciesReady": true,
      "needsUserInput": false,
      "canContinueWithoutNewMessage": true,
      "checkpointable": true
    }
  ]
}

The output itself is compatible with TodoMCP's advice input:

{
  "recommendedNow": ["task-1"],
  "deferUntilReset": [],
  "executionOrder": ["task-1"],
  "checkpoint": "Create a small verified checkpoint after the first recommended task.",
  "source": "countdown-mcp"
}

CountdownMCP does not store a queue, read TodoMCP files, import TodoMCP code, or bypass TodoMCP dependency and completion gates.

Either server continues to work normally when the other is absent.

Development

npm ci
npm run check
npm run smoke

npm run smoke uses the signed-in local Codex account and prints only the plan type and remaining percentage.

Data and security

  • The Codex live path asks Codex app-server only for account/rateLimits/read.

  • The Codex fallback parser returns only the rate_limits object and its timestamp. It never returns conversation text, authentication data, or token-usage details.

  • The Claude Code path only reads the OAuth access token already stored by Claude Code and calls Anthropic's usage endpoint with it read-only; it never writes to the credentials file and never refreshes or rotates the token itself.

  • Both tools are advertised as read-only, non-destructive, closed-world, and idempotent.

  • Runtime diagnostics go to stderr; stdout is reserved for MCP protocol messages.

Releases

Pushing a tag that exactly matches the version in package.json (for example, v0.1.0) runs the release workflow. It repeats the full check and publishes a GitHub Release containing a source ZIP and SHA-256 checksum. Users extract the ZIP and run node install.mjs; no global npm publication is required.

License

MIT License

Available Tools

2 tools
countdown_advise_workAdvise which work to doA
Read-onlyIdempotent

Use this with TodoMCP WorkCandidate v1 tasks to rank ready work against the current Codex usage window. Advisory only; it does not store tasks or override dependencies.

ParametersJSON Schema
NameRequiredDescriptionDefault
tasksYes
currentTaskIdNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
bandYes
usageYes
sourceYes
reasonsYes
checkpointNo
executionOrderYes
recommendedNowYes
deferUntilResetYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds behavioral context: 'Advisory only; it does not store tasks or override dependencies', clarifying it never mutates state. It doesn't cover errors, but output schema is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences totaling 28 words, front-loaded with the primary purpose and containing no filler or redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple advisory ranking tool, the description covers purpose, input type, and side-effect profile, and the output schema handles return values. However, it leaves ambiguous how the 'current Codex usage window' is obtained (given sibling countdown_get_usage) and does not clarify the role of currentTaskId, so it is not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%; the description does not explain any parameters. The optional currentTaskId is completely unmentioned, and while the tasks schema has self-explanatory field names, the description only hints at the structure via 'TodoMCP WorkCandidate v1 tasks', leaving the agent without additive semantic guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('rank') and resource ('ready work') against the 'current Codex usage window', and clarifies it applies to 'TodoMCP WorkCandidate v1 tasks'. It clearly differentiates from the sibling tool by noting its advisory nature.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says to use with 'TodoMCP WorkCandidate v1 tasks' and provides context ('rank ready work against the current Codex usage window'). It lacks explicit 'when not to use' or reference to the sibling countdown_get_usage as an alternative, but the advisory-only disclaimer implies no persistence.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

countdown_get_usageGet Codex usageA
Read-onlyIdempotent

Use this before large or multi-stage work to read the current Codex plan, remaining usage, reset window, credits, and limit state.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
staleYes
sourceYes
bucketsYes
creditsYes
planTypeYes
sampledAtYes
usedPercentYes
sourceTimestampYes
effectiveLimitIdYes
remainingPercentYes
spendControlReachedYes
rateLimitReachedTypeYes
resetCreditsAvailableYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this as safe and idempotent. The description adds meaningful behavioral context by specifying the exact data it returns (plan, usage, reset window, credits, limit state), which goes beyond the generic annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence beginning with the practical usage context. Every clause adds value by naming the accessible information, with no filler or redundant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only tool with an output schema and annotations, the description is complete. It covers why, when, and what to expect, making it fully sufficient for an agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the description correctly focuses on the tool's function rather than parameter details. Since there are no inputs to explain, the description fully satisfies parameter semantics without additional explanation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('read') and clearly identifies the resource and scope: current Codex plan, remaining usage, reset window, credits, and limit state. It also provides the timing for use, which further distinguishes it from the sibling tool countdown_advise_work.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool: 'before large or multi-stage work.' It gives clear context, though it does not mention when not to use it or compare with countdown_advise_work as an alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.1.0
    • First observedcountdown_advise_work
    • First observedcountdown_get_usage
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

The two tools have clearly distinct purposes: one retrieves usage information, the other provides advisory ranking for work. There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tools follow the same verb_noun pattern with the 'countdown_' prefix: countdown_get_usage and countdown_advise_work. The naming is consistent and predictable.

Tool Count3/5

With only 2 tools, the server feels thin, but it is appropriately scoped for its narrow purpose of usage monitoring and work advising. It falls into the borderline category.

Completeness4/5

The tool surface covers the core needs: reading usage and advising on work. Minor gaps exist (e.g., no explicit plan management or limit adjustment), but the described advisory scope is adequately served.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • headroom

    tyejcoleman
    A
    license
    Not graded
    quality
    A
    maintenance
    MCP server that provides real-time rate-limit and context budget awareness to Claude Code, enabling it to plan tasks that fit within its constraints and defer work when needed.
    13
    Apache 2.0

  • AAS Core (agentic-awesome

    26BB
    A
    license
    Not graded
    quality
    C
    maintenance
    A local, read-only MCP server that lets coding agents search the complete AAS skill catalog, compose and validate agent-chosen skill stacks, and generate reproducible, reviewable plans without uploading project code.
    8,426
    1
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/AlonTsur1601/CountdownMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server