openai-usage-mcp
Provides tools for querying OpenAI platform usage and cost data through the OpenAI Admin API, enabling cost analysis, month-over-month comparisons, and usage tracking for various services like completions and embeddings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@openai-usage-mcp show me March cost summary"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OpenAI Usage and Cost Management MCP Server
MCP server for accessing OpenAI platform usage and cost data through the OpenAI Admin API.
Note: This server accesses cost and usage data from the OpenAI Admin API. All API calls are performed using the caller's admin key and are subject to OpenAI's rate limits.
Features
Cost Analysis
Spend summaries: Total and per-line-item cost breakdowns with top-N ranking
Daily breakdowns: Per-day cost tracking by model or project
Projected spend: Automatic month-end projection based on current daily average
Anomaly detection: Flags daily spending spikes (>2σ from mean)
Month-over-Month Comparison
Cost variance analysis: Compare any two months side by side
Delta tracking: Per-line-item changes with dollar and percentage deltas
Biggest movers: Highlights the largest cost increases and decreases
Usage Tracking
Token consumption: Input, output, and cached token counts by model
Request volumes: API request counts over time
Multi-service support: Completions, embeddings, images, audio, moderations, vector stores, and more
Model-level breakdown: Usage aggregated by model with compact summary tables
Related MCP server: cloudscope-mcp
Prerequisites
Python 3.11 or newer
uv package manager
An OpenAI Admin API key (create one here)
Installation
Add to your MCP client configuration (e.g., Claude Desktop, Claude Code):
Using uv
{
"mcpServers": {
"openai-usage-mcp": {
"command": "uv",
"args": ["run", "--directory", "/path/to/openai-usage-mcp", "openai-usage-mcp"],
"env": {
"OPENAI_ADMIN_KEY": "sk-admin-..."
}
}
}
}Using uvx (from PyPI)
{
"mcpServers": {
"openai-usage-mcp": {
"command": "uvx",
"args": ["openai-usage-mcp"],
"env": {
"OPENAI_ADMIN_KEY": "sk-admin-..."
}
}
}
}Tools
costs
Query OpenAI dollar-amount spend data.
Parameter | Type | Default | Description |
| string | (required) | Start date (YYYY-MM-DD) |
| string | today | End date (YYYY-MM-DD) |
| string |
|
|
| string |
|
|
| int | 10 | Number of top items to show |
| int | 180 | Max daily buckets to fetch (1-180) |
Detail levels:
summary (default): Compact total + top-N breakdown table (~20 lines). Includes projected month-end spend and anomaly detection when applicable.
daily: Per-day breakdown with per-item amounts.
raw: Full unprocessed data, every line item every day.
Examples:
# This month's spend
costs(start_time="2026-03-01")
# Last 7 days by project
costs(start_time="2026-03-23", group_by="project_id")
# Daily breakdown for February
costs(start_time="2026-02-01", end_time="2026-03-01", detail_level="daily")cost-comparison
Compare OpenAI costs between two calendar months.
Parameter | Type | Default | Description |
| string | (required) | Earlier month (YYYY-MM) |
| string | (required) | Later month (YYYY-MM) |
| string |
|
|
| int | 10 | Number of top items to show |
Output includes:
Total spend for each month with overall delta and percentage change
Per-line-item comparison table sorted by largest absolute change
Biggest movers section highlighting the largest increase and decrease
Examples:
# February vs March
cost-comparison(baseline_month="2026-02", comparison_month="2026-03")
# By project
cost-comparison(baseline_month="2026-02", comparison_month="2026-03", group_by="project_id")usage
Query OpenAI token and request usage data by service type.
Parameter | Type | Default | Description |
| string | (required) | See supported types below |
| string | (required) | Start date (YYYY-MM-DD) |
| string | today | End date (YYYY-MM-DD) |
| string |
|
|
| string |
|
|
| string | — |
|
| string | — | Filter by model name(s) |
| string | — | Filter by project ID(s) |
| int | 10 | Number of top models to show |
| int | 180 | Max buckets to fetch |
Supported service types: completions, embeddings, images, audio_speeches, audio_transcriptions, moderations, vector_stores, code_interpreter_sessions
Examples:
# GPT-4o usage this month
usage(service_type="completions", start_time="2026-03-01", models="gpt-4o")
# All completions last week
usage(service_type="completions", start_time="2026-03-23")
# Embeddings by project
usage(service_type="embeddings", start_time="2026-03-01", group_by="project_id")Authentication
This server requires an OpenAI Admin API key set via the OPENAI_ADMIN_KEY environment variable.
Admin keys can be created at platform.openai.com/settings/organization/admin-keys.
The key needs the Usage read permission to access cost and usage data.
Development
# Clone and install
git clone https://github.com/dlaporte/openai-usage-mcp.git
cd openai-usage-mcp
uv sync --dev
# Run tests
uv run pytest -v
# Run the server locally
OPENAI_ADMIN_KEY=sk-admin-... uv run openai-usage-mcpLicense
MIT
Available Tools
3 toolscost-comparisonA
Compare OpenAI costs between two months to identify spending changes.
USE THIS TOOL FOR:
Month-over-month cost variance analysis (e.g., February vs March)
Identifying which line items increased or decreased the most
Executive-level cost change summaries
DO NOT USE THIS TOOL FOR:
Single-month cost analysis (use 'costs' tool instead)
Token or request usage data (use 'usage' tool instead)
Arbitrary date range comparisons (this tool compares full calendar months only)
PARAMETERS:
baseline_month: Earlier month in YYYY-MM format (e.g., "2026-02")
comparison_month: Later month in YYYY-MM format (e.g., "2026-03")
group_by: "line_item" (default), "project_id", or both
top_n: Number of items to show (default 10)
OUTPUT includes:
Total spend for each month with overall delta and % change
Per-line-item comparison table with delta and % change
Biggest movers section highlighting largest increase and decrease
EXAMPLES:
February vs March: baseline_month="2026-02", comparison_month="2026-03"
By project: baseline_month="2026-02", comparison_month="2026-03", group_by="project_id"
Inputs: baseline_month (required), comparison_month (required), top_n, group_by. Returns: result
costsA
Query OpenAI dollar-amount spend data.
USE THIS TOOL FOR:
Total spend over a date range (summary mode, default)
Daily cost breakdown by line item or project
Month-to-date spend with projected month-end forecast
Identifying cost anomalies (spike days highlighted in summary)
DO NOT USE THIS TOOL FOR:
Token or request counts (use 'usage' tool instead)
Comparing two different months side by side (use 'cost-comparison' tool)
DETAIL LEVELS:
summary (default): Compact total + top-N breakdown table (~20 lines). Includes projected month-end spend and anomaly detection when applicable.
daily: Per-day breakdown with per-item amounts.
raw: Full unprocessed data, every line item every day.
DEFAULTS: detail_level='summary', group_by='line_item', top_n=10, end_time=today
EXAMPLES:
This month's spend: start_time="2026-03-01"
Last 7 days by project: start_time="2026-03-23", group_by="project_id"
Daily breakdown for February: start_time="2026-02-01", end_time="2026-03-01", detail_level="daily"
Dates in YYYY-MM-DD format.
Inputs: start_time (required), top_n, end_time, group_by, +1 more. Returns: result
usageA
Query OpenAI token and request usage data by service type.
USE THIS TOOL FOR:
Token consumption (input, output, cached) by model
Request counts over time
Usage breakdown by model, project, or API key
Image generation counts, audio seconds, etc.
DO NOT USE THIS TOOL FOR:
Dollar-amount costs (use 'costs' tool instead)
Month-over-month cost comparisons (use 'cost-comparison' tool)
SERVICE TYPES: completions, embeddings, images, audio_speeches, audio_transcriptions, moderations, vector_stores, code_interpreter_sessions
DETAIL LEVELS:
summary (default): Compact table aggregated by model with totals.
daily: Per-day breakdown.
raw: Full unprocessed data.
DEFAULTS: detail_level='summary', bucket_width='1d', top_n=10, end_time=today
EXAMPLES:
GPT-4o usage this month: service_type="completions", start_time="2026-03-01", models="gpt-4o"
All completions last week: service_type="completions", start_time="2026-03-23"
Embeddings by project: service_type="embeddings", start_time="2026-03-01", group_by="project_id"
Dates in YYYY-MM-DD format.
Inputs: start_time (required), service_type (required), top_n, models, +5 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: costs for dollar spend, usage for token/request counts, and cost-comparison for month-over-month variance. The descriptions explicitly cross-reference 'DO NOT USE THIS TOOL FOR' statements, eliminating ambiguity.
Tool names are primarily single-word nouns (costs, usage) with one hyphenated compound (cost-comparison). While not following a verb_noun pattern, the names are short and readable, though the hyphen introduces a minor inconsistency.
Three tools is a well-scoped count for an OpenAI usage/cost tracking server. Each tool covers a distinct aspect of the domain (cost, usage, comparison) and fits within the ideal 3-15 tool range.
The surface covers the core domain of cost and usage tracking, including summary, daily, and raw detail levels, plus month-over-month cost comparison. Missing a dedicated usage-comparison tool or project/service listing, but these are minor and can be worked around via parameters.
Maintenance
Related MCP Connectors
Analytics for MCP servers. Query your tool calls, first-call success, retries and schema cost.
Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.
OpenAI organization usage and cost reporting through an admin API key connected by the user.
Hosted MCP server for AWS cloud spend: service breakdowns, anomalies, savings and forecasts.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server for unified cost tracking and analysis across AWS, OpenAI, and Anthropic. It enables users to query expenditures, compare costs across providers, and analyze usage trends through natural language.10MIT
- AlicenseAqualityCmaintenanceCloud cost management MCP server for Azure. Ask your AI about your cloud bill.15104 npm1MIT
- AlicenseAqualityCmaintenanceA read-only MCP server for querying AI provider administration APIs, providing normalized usage, cost, and dashboard data for OpenAI and Anthropic.415 npmMIT
- AlicenseNot gradedqualityDmaintenanceMCP server that reads local OpenClaw session files to provide token usage and cost data without any network calls or authentication.MIT