Openai Usage

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

Prerequisites

1. Python 3.11 or newer
2. uv package manager
3. 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
start_time	string	(required)	Start date (YYYY-MM-DD)
end_time	string	today	End date (YYYY-MM-DD)
detail_level	string	"summary"	"summary", "daily", or "raw"
group_by	string	"line_item"	"line_item", "project_id", or both
top_n	int	10	Number of top items to show
limit	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
baseline_month	string	(required)	Earlier month (YYYY-MM)
comparison_month	string	(required)	Later month (YYYY-MM)
group_by	string	"line_item"	"line_item", "project_id", or both
top_n	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
service_type	string	(required)	See supported types below
start_time	string	(required)	Start date (YYYY-MM-DD)
end_time	string	today	End date (YYYY-MM-DD)
detail_level	string	"summary"	"summary" or "raw"
bucket_width	string	"1d"	"1m", "1h", or "1d"
group_by	string	—	"model", "project_id", etc.
models	string	—	Filter by model name(s)
project_ids	string	—	Filter by project ID(s)
top_n	int	10	Number of top models to show
limit	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-mcp

License

MIT