Skip to main content
Glama
openai-usage-mcp

openai-usage-mcp

by dlaporte

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

  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

Available Tools

3 tools
cost-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

    A4.7/5.0

    Scored across 3 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers