OpenCodex Quota MCP

English | 简体中文

A small, read-only MCP server that lets tool-capable models in Codex query provider quotas, balances and reset times from the local OpenCodex dashboard.

This is an independent third-party integration, not an official OpenCodex or OpenAI plugin. OpenCodex supplies the provider connections, authentication, quota collection and dashboard. This project exposes that existing data as one MCP tool; it does not implement its own provider billing integrations. See Acknowledgements.

What it does

• Lists configured providers or filters by an exact provider name or dashboard label, case-insensitively.

• Returns used and remaining percentages, balance text, reset times and measurement timestamps when available.

• Keeps OpenAI account-pool aggregates separate from the current account's quota.

• Marks missing readings as unavailable_or_unsupported, rather than treating them as zero usage.

• Keeps dashboard session tokens, CSRF tokens, API keys and provider request headers out of tool results.

Related MCP server: openclaw-usage-mcp

Requirements

• Node.js 22 or newer, npm, and Git if cloning.

• A working OpenCodex installation, with configured providers and a dashboard accessible at http://localhost:10100.

• Codex or another client supporting local stdio MCP servers, and a model that supports tool calls.

• The MCP process and OpenCodex must run on the same machine. The dashboard address is fixed in this version.

Validated locally with OpenCodex 2.93.0, Node.js 24, and Windows. Ubuntu/Windows with Node.js 22/24 are included in CI for the offline tests. OpenCodex's dashboard interfaces are internal APIs and may change between versions. Remote dashboards and authentication setups that do not issue a local dashboard session are not supported.

Install in Codex

1. Download and install dependencies

git clone https://github.com/wujiseclusion/opencodex-quota-mcp.git
cd opencodex-quota-mcp
npm ci

Alternatively, download and extract a release, then run npm ci inside the extracted directory. Keep this directory in a permanent location: Codex will launch the server from it.

2. Register the local MCP server

Windows PowerShell, from the project directory:

$nodePath = (Get-Command node).Source
$serverPath = (Resolve-Path ./server.mjs).Path
codex mcp add opencodex-quota -- $nodePath $serverPath
codex mcp get opencodex-quota

macOS / Linux, from the project directory:

codex mcp add opencodex-quota -- "$(command -v node)" "$(pwd)/server.mjs"
codex mcp get opencodex-quota

If opencodex-quota is already registered and you want to replace it, run codex mcp remove opencodex-quota first. You can also configure it manually in ~/.codex/config.toml, using your own absolute paths:

[mcp_servers.opencodex-quota]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/opencodex-quota-mcp/server.mjs"]
tool_timeout_sec = 150

On Windows, forward slashes work in TOML paths, for example C:/tools/opencodex-quota-mcp/server.mjs. The optional 150-second timeout allows for slow dashboard queries and a single authentication retry. See the official Codex MCP documentation for client configuration.

3. Start a new Codex chat

Make sure OpenCodex is running, then start a new chat. If the tool is missing, check MCP settings and restart Codex if necessary. Ask:

Use get_provider_quotas to show all provider quotas, balances and reset times. Include the measurement time.

Or:

Check the remaining Anthropic quota with get_provider_quotas.

Tool reference

get_provider_quotas accepts one optional argument:

{}

{ "provider": "anthropic" }

Use the exact configured provider name or dashboard label. For example, anthropic, openai, deepseek or kimi, if configured. Omit the argument to discover names. No arbitrary URL, credential or write-operation parameters are exposed.

All output timestamps use UTC ISO 8601. Convert them to the user's timezone when presenting them. For a pool, nextRecoveryAt describes the next capacity recovery, which is different from a full pool reset.

Data access and limitations

The server fetches the local dashboard HTML to obtain its session, then sends authenticated GET requests to /api/providers and /api/provider-quotas. Authentication is held in process memory and is not written to files. HTTP redirects are rejected. A 401/403 response triggers one session renewal and retry per request. Responses are projected to quota-related fields rather than forwarding provider configurations.

The tool uses OpenCodex's existing cache policy. It does not pass refresh=1, send model completions, change routing or modify provider settings. OpenCodex may itself contact providers or update its own caches while serving its quota endpoint. This is an on-demand query tool, not a background monitor.

Quota availability depends on OpenCodex and the upstream provider. A configured provider can have no supported quota interface or no current reading. This server cannot add missing upstream quota support. Balance-only readings are returned as balance text, without interpreting the dashboard's placeholder percentage. Model tool-call support must be checked separately; not every routed model has been tested.

Test

npm test

Runs offline fixtures and a real stdio MCP handshake/tool-discovery test. It does not require OpenCodex, provider credentials or live quota queries. The live test is skipped by default.

With a running local OpenCodex dashboard and at least one configured provider:

npm run test:live

Runs the same suite plus real quota queries, provider filtering and unknown-provider handling. Live provider names/statuses may appear in the console; avoid sharing logs if those names are private. live-test.env only enables this test and contains no credentials.

Troubleshooting

Update / uninstall

Update from a Git checkout with git pull --ff-only followed by npm ci, then restart the MCP client. If the installation path changes, remove and register the MCP entry again.

codex mcp remove opencodex-quota

Then remove the project directory if no longer needed. This does not uninstall OpenCodex.

Acknowledgements

• OpenCodex — lidge-jun/opencodex: the upstream proxy and dashboard this integration depends on; provider authentication, quota measurements and labels come from OpenCodex. Its code is licensed under MIT.

• Model Context Protocol TypeScript SDK: stdio MCP server and client implementation.

This repository contains an independently written adapter; it does not bundle OpenCodex. Project names belong to their respective owners. This adapter is licensed under MIT.