openai-usage-mcp

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

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