Skip to main content
Glama
komaksym

chatgpt-quota-mcp

by komaksym
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

ChatGPT Quota MCP

A single local MCP tool that lets ChatGPT read your current ChatGPT/Codex quota through your already signed-in Codex CLI.

ChatGPT
   |
Secure MCP Tunnel
   |
get_chatgpt_quota (local MCP)
   |
codex app-server --stdio
   |
account/rateLimits/read

What it returns

The server exposes one no-argument tool:

get_chatgpt_quota()

Example result:

{
  "source": "codex_app_server",
  "windows": [
    {
      "name": "primary",
      "used_percent": 25.0,
      "remaining_percent": 75.0,
      "window_minutes": 300,
      "resets_at": 1786543200
    }
  ],
  "rate_limit_reached_type": null,
  "individual_limit": null,
  "spend_control_reached": null,
  "reset_credits": null
}

The tool does not assume that primary means 5-hour or secondary means weekly. It reports the window duration Codex actually returns.

Related MCP server: copilot-status-mcp

Prerequisites

  • Python 3.11+

  • uv

  • Codex CLI available as codex

  • Codex CLI already signed in to the ChatGPT account whose quota you want to read

Verify the last two with:

command -v codex
codex

Install

git clone https://github.com/komaksym/chatgpt-quota-mcp.git
cd chatgpt-quota-mcp
uv sync --extra dev

Test the quota locally first

This bypasses MCP and proves that the Codex quota read works on your machine:

uv run python -c 'from chatgpt_quota_mcp.service import get_chatgpt_quota; import json; print(json.dumps(get_chatgpt_quota(), indent=2))'

If that prints your quota, the Codex side is working.

Connect it to ChatGPT

OpenAI Secure MCP Tunnel can launch a local stdio MCP command, so this project does not need an HTTP server or public port.

  1. In OpenAI Platform tunnel settings, create a tunnel associated with the ChatGPT workspace you will use and obtain a tunnel_id plus runtime API key.

  2. Install the current tunnel-client from OpenAI's tunnel settings/download instructions.

  3. Configure the tunnel to launch this project's MCP executable:

export CONTROL_PLANE_API_KEY="sk-..."

TUNNEL_ID="tunnel_..."
MCP_COMMAND="$(pwd)/.venv/bin/chatgpt-quota-mcp"

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile chatgpt-quota \
  --tunnel-id "$TUNNEL_ID" \
  --mcp-command "$MCP_COMMAND"

tunnel-client doctor --profile chatgpt-quota --explain
tunnel-client run --profile chatgpt-quota

Do not commit the runtime API key.

  1. In ChatGPT, enable Settings -> Security and login -> Developer mode.

  2. Open ChatGPT Plugins, press +, choose Tunnel under Connection, and select or paste your tunnel_id.

  3. Confirm that ChatGPT discovers exactly one tool: get_chatgpt_quota.

Then ask:

How much Codex quota do I have left?

Development

uv sync --extra dev
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest
uv build

The test suite includes a real MCP stdio round trip backed by a fake Codex executable, so CI exercises the full local protocol chain without using a real account.

Why this shape

The Codex App Server has a stable account/rateLimits/read method. Using that structured interface is smaller and less brittle than scraping ChatGPT UI text or calling undocumented ChatGPT backend endpoints.

References

Available Tools

1 tool
get_chatgpt_quotaA

Return current ChatGPT/Codex quota windows, remaining usage, and reset times.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description carries the full burden. It indicates a read-only behavior via 'Return' and describes a point-in-time snapshot with 'current'. It does not mention side effects or quota consumption, but the nature of the tool is clearly non-mutating and transparent for an agent to infer.

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 sentence that is front-loaded with the verb 'Return' and lists the key data items. Every word adds value, with no fluff or redundancy.

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 tool with an output schema, the description fully captures the tool's purpose and expected data. The itemized list of returned data (quota windows, remaining usage, reset times) is sufficient for an agent, and the output schema provides detailed structure.

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, so the description trivially covers all schema semantics. The baseline for 0-parameter tools is 4, and the description adds no extra parameter information because none exists.

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 the specific verb 'Return' and clearly identifies the resource (ChatGPT/Codex quota) and the data provided (quota windows, remaining usage, reset times). It is unambiguous and fully distinguishes the tool's function, even without siblings.

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 implies the tool should be used to check current quota status before making calls. It clearly states what data is returned, providing context for when to use it. No exclusions or alternatives are needed since there are no sibling tools, but explicit when-to-use guidance is minimal.

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

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.6/5.0
Disambiguation5/5

Only one tool exists, so there is no possibility of overlap or confusion. The tool's purpose is unambiguous and clearly distinct.

Naming Consistency5/5

The single tool name 'get_chatgpt_quota' follows a clear verb_noun pattern, consistent with common MCP server conventions. Since there's only one tool, consistency is trivially maintained.

Tool Count4/5

The server has a focused scope on ChatGPT quota; one tool is minimal but appropriate for a read-only quota endpoint. It sits on the low end of typical counts but is not excessive for the stated purpose.

Completeness5/5

The tool provides a complete picture of quota status including windows, usage, and reset times. For a quota-information server, there are no obvious missing operations.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

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/komaksym/chatgpt-quota-mcp'

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