openai-admin-usage-mcp-server 0.1.0__tar.gz

openai_admin_usage_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: openai-admin-usage-mcp-server
+Version: 0.1.0
+Summary: MCP server exposing OpenAI organization costs endpoint as a tool
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.6.0
+Requires-Dist: httpx>=0.27.0

openai_admin_usage_mcp_server-0.1.0/README.md

@@ -0,0 +1,145 @@
+# OpenAI Admin Usage MCP Server (Python)
+
+This MCP server exposes tools:
+
+- `get_organization_costs` -> calls `GET /v1/organization/costs`
+- `get_organization_usage_completions` -> calls `GET /v1/organization/usage/completions`
+- `get_organization_usage_audio_speeches` -> calls `GET /v1/organization/usage/audio_speeches`
+- `get_organization_usage_audio_transcriptions` -> calls `GET /v1/organization/usage/audio_transcriptions`
+- `get_organization_usage_code_interpreter_sessions` -> calls `GET /v1/organization/usage/code_interpreter_sessions`
+- `get_organization_usage_embeddings` -> calls `GET /v1/organization/usage/embeddings`
+- `get_organization_usage_images` -> calls `GET /v1/organization/usage/images`
+- `get_organization_usage_moderations` -> calls `GET /v1/organization/usage/moderations`
+- `get_organization_usage_vector_stores` -> calls `GET /v1/organization/usage/vector_stores`
+- `get_organization_users` -> calls `GET /v1/organization/users`
+- `get_organization_user` -> calls `GET /v1/organization/users/{user_id}`
+- `get_organization_projects` -> calls `GET /v1/organization/projects`
+
+Both tools auto-follow pagination and return only merged `data` (no pagination fields in output).
+
+## Requirements
+
+- Python 3.10+
+- OpenAI Admin key in `OPENAI_ADMIN_KEY` (preferred) or `OPENAI_API_KEY`
+
+## Install
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Run
+
+```bash
+export OPENAI_ADMIN_KEY="your_admin_key"
+openai-admin-usage-mcp-server
+```
+
+## Tool Input
+
+### `get_organization_costs`
+
+- `start_time` (required, integer Unix seconds)
+- `bucket_width` (optional, default `"1d"`)
+- `end_time` (optional, integer Unix seconds)
+- `group_by` (optional array; allowed values: `"project_id"`, `"line_item"`; you can pass one or both)
+- `project_ids` (optional, list of project IDs)
+
+### `get_organization_usage_completions`
+
+- `start_time` (required, integer Unix seconds)
+- `bucket_width` (optional, `"1m"` / `"1h"` / `"1d"`, default `"1d"`)
+- `end_time` (optional, integer Unix seconds)
+- `group_by` (optional array; allowed values: `"project_id"`, `"user_id"`, `"api_key_id"`, `"model"`, `"batch"`, `"service_tier"`; any combination is allowed)
+- `project_ids` (optional, list of project IDs)
+- `user_ids` (optional, list of user IDs)
+- `api_key_ids` (optional, list of API key IDs)
+- `models` (optional, list of model names)
+- `batch` (optional, boolean)
+
+### `get_organization_usage_audio_speeches`
+
+- `start_time` (required, integer Unix seconds)
+- `bucket_width` (optional, `"1m"` / `"1h"` / `"1d"`, default `"1d"`)
+- `end_time` (optional, integer Unix seconds)
+- `group_by` (optional array; allowed values: `"project_id"`, `"user_id"`, `"api_key_id"`, `"model"`; any combination is allowed)
+- `project_ids` (optional, list of project IDs)
+- `user_ids` (optional, list of user IDs)
+- `api_key_ids` (optional, list of API key IDs)
+- `models` (optional, list of model names)
+
+### `get_organization_usage_audio_transcriptions`
+
+- `start_time` (required, integer Unix seconds)
+- `bucket_width` (optional, `"1m"` / `"1h"` / `"1d"`, default `"1d"`)
+- `end_time` (optional, integer Unix seconds)
+- `group_by` (optional array; allowed values: `"project_id"`, `"user_id"`, `"api_key_id"`, `"model"`; any combination is allowed)
+- `project_ids` (optional, list of project IDs)
+- `user_ids` (optional, list of user IDs)
+- `api_key_ids` (optional, list of API key IDs)
+- `models` (optional, list of model names)
+
+### `get_organization_usage_code_interpreter_sessions`
+
+- `start_time` (required, integer Unix seconds)
+- `bucket_width` (optional, `"1m"` / `"1h"` / `"1d"`, default `"1d"`)
+- `end_time` (optional, integer Unix seconds)
+- `group_by` (optional array; only `"project_id"` is allowed)
+- `project_ids` (optional, list of project IDs)
+
+### `get_organization_usage_embeddings`
+
+- `start_time` (required, integer Unix seconds)
+- `bucket_width` (optional, `"1m"` / `"1h"` / `"1d"`, default `"1d"`)
+- `end_time` (optional, integer Unix seconds)
+- `group_by` (optional array; allowed values: `"project_id"`, `"user_id"`, `"api_key_id"`, `"model"`; any combination is allowed)
+- `project_ids` (optional, list of project IDs)
+- `user_ids` (optional, list of user IDs)
+- `api_key_ids` (optional, list of API key IDs)
+- `models` (optional, list of model names)
+
+### `get_organization_usage_images`
+
+- `start_time` (required, integer Unix seconds)
+- `bucket_width` (optional, `"1m"` / `"1h"` / `"1d"`, default `"1d"`)
+- `end_time` (optional, integer Unix seconds)
+- `group_by` (optional array; allowed values: `"project_id"`, `"user_id"`, `"api_key_id"`, `"model"`, `"size"`, `"source"`; any combination is allowed)
+- `project_ids` (optional, list of project IDs)
+- `user_ids` (optional, list of user IDs)
+- `api_key_ids` (optional, list of API key IDs)
+- `models` (optional, list of model names)
+- `sizes` (optional, list of `256x256`, `512x512`, `1024x1024`, `1792x1792`, `1024x1792`)
+- `sources` (optional, list of `image.generation`, `image.edit`, `image.variation`)
+
+### `get_organization_usage_moderations`
+
+- `start_time` (required, integer Unix seconds)
+- `bucket_width` (optional, `"1m"` / `"1h"` / `"1d"`, default `"1d"`)
+- `end_time` (optional, integer Unix seconds)
+- `group_by` (optional array; allowed values: `"project_id"`, `"user_id"`, `"api_key_id"`, `"model"`; any combination is allowed)
+- `project_ids` (optional, list of project IDs)
+- `user_ids` (optional, list of user IDs)
+- `api_key_ids` (optional, list of API key IDs)
+- `models` (optional, list of model names)
+
+### `get_organization_usage_vector_stores`
+
+- `start_time` (required, integer Unix seconds)
+- `bucket_width` (optional, `"1m"` / `"1h"` / `"1d"`, default `"1d"`)
+- `end_time` (optional, integer Unix seconds)
+- `group_by` (optional array; only `"project_id"` is allowed)
+- `project_ids` (optional, list of project IDs)
+
+### `get_organization_users`
+
+- `emails` (optional, list of email addresses to filter users)
+
+### `get_organization_user`
+
+- `user_id` (required, organization user ID string)
+
+### `get_organization_projects`
+
+- `include_archived` (optional, boolean; if true includes archived projects)

openai_admin_usage_mcp_server-0.1.0/openai_admin_usage_mcp_server.egg-info/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: openai-admin-usage-mcp-server
+Version: 0.1.0
+Summary: MCP server exposing OpenAI organization costs endpoint as a tool
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.6.0
+Requires-Dist: httpx>=0.27.0

openai_admin_usage_mcp_server-0.1.0/openai_admin_usage_mcp_server.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+server.py
+openai_admin_usage_mcp_server.egg-info/PKG-INFO
+openai_admin_usage_mcp_server.egg-info/SOURCES.txt
+openai_admin_usage_mcp_server.egg-info/dependency_links.txt
+openai_admin_usage_mcp_server.egg-info/entry_points.txt
+openai_admin_usage_mcp_server.egg-info/requires.txt
+openai_admin_usage_mcp_server.egg-info/top_level.txt

openai_admin_usage_mcp_server-0.1.0/openai_admin_usage_mcp_server.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openai_admin_usage_mcp_server-0.1.0/openai_admin_usage_mcp_server.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+openai-admin-usage-mcp-server = server:main

openai_admin_usage_mcp_server-0.1.0/openai_admin_usage_mcp_server.egg-info/requires.txt

@@ -0,0 +1,2 @@
+mcp>=1.6.0
+httpx>=0.27.0

openai_admin_usage_mcp_server-0.1.0/openai_admin_usage_mcp_server.egg-info/top_level.txt

@@ -0,0 +1 @@
+server

openai_admin_usage_mcp_server-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "openai-admin-usage-mcp-server"
+version = "0.1.0"
+description = "MCP server exposing OpenAI organization costs endpoint as a tool"
+requires-python = ">=3.10"
+dependencies = [
+  "mcp>=1.6.0",
+  "httpx>=0.27.0",
+]
+
+[project.scripts]
+openai-admin-usage-mcp-server = "server:main"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"

openai_admin_usage_mcp_server-0.1.0/server.py

@@ -0,0 +1,998 @@
+"""MCP server tools for OpenAI organization usage/costs.
+
+All tools auto-follow pagination and return merged output as {"data": [...]}.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+OPENAI_COSTS_URL = "https://api.openai.com/v1/organization/costs"
+OPENAI_USAGE_COMPLETIONS_URL = "https://api.openai.com/v1/organization/usage/completions"
+OPENAI_USAGE_AUDIO_SPEECHES_URL = "https://api.openai.com/v1/organization/usage/audio_speeches"
+OPENAI_USAGE_AUDIO_TRANSCRIPTIONS_URL = "https://api.openai.com/v1/organization/usage/audio_transcriptions"
+OPENAI_USAGE_CODE_INTERPRETER_SESSIONS_URL = "https://api.openai.com/v1/organization/usage/code_interpreter_sessions"
+OPENAI_USAGE_EMBEDDINGS_URL = "https://api.openai.com/v1/organization/usage/embeddings"
+OPENAI_USAGE_IMAGES_URL = "https://api.openai.com/v1/organization/usage/images"
+OPENAI_USAGE_MODERATIONS_URL = "https://api.openai.com/v1/organization/usage/moderations"
+OPENAI_USAGE_VECTOR_STORES_URL = "https://api.openai.com/v1/organization/usage/vector_stores"
+OPENAI_ORGANIZATION_USERS_URL = "https://api.openai.com/v1/organization/users"
+OPENAI_ORGANIZATION_PROJECTS_URL = "https://api.openai.com/v1/organization/projects"
+ALLOWED_COSTS_GROUP_BY = {"project_id", "line_item"}
+ALLOWED_COMPLETIONS_BUCKET_WIDTH = {"1m", "1h", "1d"}
+ALLOWED_COMPLETIONS_GROUP_BY = {
+    "project_id",
+    "user_id",
+    "api_key_id",
+    "model",
+    "batch",
+    "service_tier",
+}
+ALLOWED_AUDIO_SPEECHES_GROUP_BY = {
+    "project_id",
+    "user_id",
+    "api_key_id",
+    "model",
+}
+ALLOWED_AUDIO_TRANSCRIPTIONS_GROUP_BY = {
+    "project_id",
+    "user_id",
+    "api_key_id",
+    "model",
+}
+ALLOWED_CODE_INTERPRETER_SESSIONS_GROUP_BY = {"project_id"}
+ALLOWED_EMBEDDINGS_GROUP_BY = {
+    "project_id",
+    "user_id",
+    "api_key_id",
+    "model",
+}
+ALLOWED_IMAGES_GROUP_BY = {
+    "project_id",
+    "user_id",
+    "api_key_id",
+    "model",
+    "size",
+    "source",
+}
+ALLOWED_IMAGES_SIZES = {"256x256", "512x512", "1024x1024", "1792x1792", "1024x1792"}
+ALLOWED_IMAGES_SOURCES = {"image.generation", "image.edit", "image.variation"}
+ALLOWED_MODERATIONS_GROUP_BY = {
+    "project_id",
+    "user_id",
+    "api_key_id",
+    "model",
+}
+ALLOWED_VECTOR_STORES_GROUP_BY = {"project_id"}
+
+mcp = FastMCP("openai-admin-usage")
+
+
+def _validate_costs_inputs(
+    start_time: int,
+    bucket_width: str,
+    end_time: int | None,
+    group_by: list[str] | None,
+    project_ids: list[str] | None,
+) -> None:
+    if not isinstance(start_time, int):
+        raise ValueError("`start_time` is required and must be a Unix timestamp in seconds.")
+
+    if bucket_width != "1d":
+        raise ValueError("`bucket_width` currently supports only `1d`.")
+
+    if end_time is not None and not isinstance(end_time, int):
+        raise ValueError("`end_time` must be a Unix timestamp in seconds.")
+
+    if group_by is not None:
+        if not isinstance(group_by, list):
+            raise ValueError("`group_by` must be an array.")
+        invalid = [value for value in group_by if value not in ALLOWED_COSTS_GROUP_BY]
+        if invalid:
+            raise ValueError(
+                "`group_by` supports only `project_id` and `line_item`."
+            )
+
+    if project_ids is not None:
+        if not isinstance(project_ids, list) or not all(
+            isinstance(item, str) for item in project_ids
+        ):
+            raise ValueError("`project_ids` must be an array of strings.")
+
+
+def _validate_string_list(value: list[str] | None, field_name: str) -> None:
+    if value is not None and (
+        not isinstance(value, list) or not all(isinstance(item, str) for item in value)
+    ):
+        raise ValueError(f"`{field_name}` must be an array of strings.")
+
+
+def _validate_completions_inputs(
+    start_time: int,
+    bucket_width: str,
+    end_time: int | None,
+    group_by: list[str] | None,
+    project_ids: list[str] | None,
+    user_ids: list[str] | None,
+    api_key_ids: list[str] | None,
+    models: list[str] | None,
+    batch: bool | None,
+) -> None:
+    if not isinstance(start_time, int):
+        raise ValueError("`start_time` is required and must be a Unix timestamp in seconds.")
+
+    if bucket_width not in ALLOWED_COMPLETIONS_BUCKET_WIDTH:
+        raise ValueError("`bucket_width` supports only `1m`, `1h`, or `1d`.")
+
+    if end_time is not None and not isinstance(end_time, int):
+        raise ValueError("`end_time` must be a Unix timestamp in seconds.")
+
+    if group_by is not None:
+        if not isinstance(group_by, list):
+            raise ValueError("`group_by` must be an array.")
+        invalid = [value for value in group_by if value not in ALLOWED_COMPLETIONS_GROUP_BY]
+        if invalid:
+            raise ValueError(
+                "`group_by` supports only project_id, user_id, api_key_id, "
+                "model, batch, service_tier."
+            )
+
+    _validate_string_list(project_ids, "project_ids")
+    _validate_string_list(user_ids, "user_ids")
+    _validate_string_list(api_key_ids, "api_key_ids")
+    _validate_string_list(models, "models")
+
+    if batch is not None and not isinstance(batch, bool):
+        raise ValueError("`batch` must be a boolean.")
+
+
+def _validate_audio_speeches_inputs(
+    start_time: int,
+    bucket_width: str,
+    end_time: int | None,
+    group_by: list[str] | None,
+    project_ids: list[str] | None,
+    user_ids: list[str] | None,
+    api_key_ids: list[str] | None,
+    models: list[str] | None,
+) -> None:
+    if not isinstance(start_time, int):
+        raise ValueError("`start_time` is required and must be a Unix timestamp in seconds.")
+
+    if bucket_width not in ALLOWED_COMPLETIONS_BUCKET_WIDTH:
+        raise ValueError("`bucket_width` supports only `1m`, `1h`, or `1d`.")
+
+    if end_time is not None and not isinstance(end_time, int):
+        raise ValueError("`end_time` must be a Unix timestamp in seconds.")
+
+    if group_by is not None:
+        if not isinstance(group_by, list):
+            raise ValueError("`group_by` must be an array.")
+        invalid = [value for value in group_by if value not in ALLOWED_AUDIO_SPEECHES_GROUP_BY]
+        if invalid:
+            raise ValueError(
+                "`group_by` supports only project_id, user_id, api_key_id, model."
+            )
+
+    _validate_string_list(project_ids, "project_ids")
+    _validate_string_list(user_ids, "user_ids")
+    _validate_string_list(api_key_ids, "api_key_ids")
+    _validate_string_list(models, "models")
+
+
+def _validate_audio_transcriptions_inputs(
+    start_time: int,
+    bucket_width: str,
+    end_time: int | None,
+    group_by: list[str] | None,
+    project_ids: list[str] | None,
+    user_ids: list[str] | None,
+    api_key_ids: list[str] | None,
+    models: list[str] | None,
+) -> None:
+    if not isinstance(start_time, int):
+        raise ValueError("`start_time` is required and must be a Unix timestamp in seconds.")
+
+    if bucket_width not in ALLOWED_COMPLETIONS_BUCKET_WIDTH:
+        raise ValueError("`bucket_width` supports only `1m`, `1h`, or `1d`.")
+
+    if end_time is not None and not isinstance(end_time, int):
+        raise ValueError("`end_time` must be a Unix timestamp in seconds.")
+
+    if group_by is not None:
+        if not isinstance(group_by, list):
+            raise ValueError("`group_by` must be an array.")
+        invalid = [
+            value for value in group_by if value not in ALLOWED_AUDIO_TRANSCRIPTIONS_GROUP_BY
+        ]
+        if invalid:
+            raise ValueError(
+                "`group_by` supports only project_id, user_id, api_key_id, model."
+            )
+
+    _validate_string_list(project_ids, "project_ids")
+    _validate_string_list(user_ids, "user_ids")
+    _validate_string_list(api_key_ids, "api_key_ids")
+    _validate_string_list(models, "models")
+
+
+def _validate_code_interpreter_sessions_inputs(
+    start_time: int,
+    bucket_width: str,
+    end_time: int | None,
+    group_by: list[str] | None,
+    project_ids: list[str] | None,
+) -> None:
+    if not isinstance(start_time, int):
+        raise ValueError("`start_time` is required and must be a Unix timestamp in seconds.")
+
+    if bucket_width not in ALLOWED_COMPLETIONS_BUCKET_WIDTH:
+        raise ValueError("`bucket_width` supports only `1m`, `1h`, or `1d`.")
+
+    if end_time is not None and not isinstance(end_time, int):
+        raise ValueError("`end_time` must be a Unix timestamp in seconds.")
+
+    if group_by is not None:
+        if not isinstance(group_by, list):
+            raise ValueError("`group_by` must be an array.")
+        invalid = [
+            value
+            for value in group_by
+            if value not in ALLOWED_CODE_INTERPRETER_SESSIONS_GROUP_BY
+        ]
+        if invalid:
+            raise ValueError("`group_by` supports only `project_id`.")
+
+    _validate_string_list(project_ids, "project_ids")
+
+
+def _validate_embeddings_inputs(
+    start_time: int,
+    bucket_width: str,
+    end_time: int | None,
+    group_by: list[str] | None,
+    project_ids: list[str] | None,
+    user_ids: list[str] | None,
+    api_key_ids: list[str] | None,
+    models: list[str] | None,
+) -> None:
+    if not isinstance(start_time, int):
+        raise ValueError("`start_time` is required and must be a Unix timestamp in seconds.")
+
+    if bucket_width not in ALLOWED_COMPLETIONS_BUCKET_WIDTH:
+        raise ValueError("`bucket_width` supports only `1m`, `1h`, or `1d`.")
+
+    if end_time is not None and not isinstance(end_time, int):
+        raise ValueError("`end_time` must be a Unix timestamp in seconds.")
+
+    if group_by is not None:
+        if not isinstance(group_by, list):
+            raise ValueError("`group_by` must be an array.")
+        invalid = [value for value in group_by if value not in ALLOWED_EMBEDDINGS_GROUP_BY]
+        if invalid:
+            raise ValueError(
+                "`group_by` supports only project_id, user_id, api_key_id, model."
+            )
+
+    _validate_string_list(project_ids, "project_ids")
+    _validate_string_list(user_ids, "user_ids")
+    _validate_string_list(api_key_ids, "api_key_ids")
+    _validate_string_list(models, "models")
+
+
+def _validate_images_inputs(
+    start_time: int,
+    bucket_width: str,
+    end_time: int | None,
+    group_by: list[str] | None,
+    project_ids: list[str] | None,
+    user_ids: list[str] | None,
+    api_key_ids: list[str] | None,
+    models: list[str] | None,
+    sizes: list[str] | None,
+    sources: list[str] | None,
+) -> None:
+    if not isinstance(start_time, int):
+        raise ValueError("`start_time` is required and must be a Unix timestamp in seconds.")
+
+    if bucket_width not in ALLOWED_COMPLETIONS_BUCKET_WIDTH:
+        raise ValueError("`bucket_width` supports only `1m`, `1h`, or `1d`.")
+
+    if end_time is not None and not isinstance(end_time, int):
+        raise ValueError("`end_time` must be a Unix timestamp in seconds.")
+
+    if group_by is not None:
+        if not isinstance(group_by, list):
+            raise ValueError("`group_by` must be an array.")
+        invalid = [value for value in group_by if value not in ALLOWED_IMAGES_GROUP_BY]
+        if invalid:
+            raise ValueError(
+                "`group_by` supports only project_id, user_id, api_key_id, model, size, source."
+            )
+
+    _validate_string_list(project_ids, "project_ids")
+    _validate_string_list(user_ids, "user_ids")
+    _validate_string_list(api_key_ids, "api_key_ids")
+    _validate_string_list(models, "models")
+    _validate_string_list(sizes, "sizes")
+    _validate_string_list(sources, "sources")
+
+    if sizes is not None:
+        invalid_sizes = [size for size in sizes if size not in ALLOWED_IMAGES_SIZES]
+        if invalid_sizes:
+            raise ValueError(
+                "`sizes` supports only 256x256, 512x512, 1024x1024, 1792x1792, 1024x1792."
+            )
+
+    if sources is not None:
+        invalid_sources = [source for source in sources if source not in ALLOWED_IMAGES_SOURCES]
+        if invalid_sources:
+            raise ValueError(
+                "`sources` supports only image.generation, image.edit, image.variation."
+            )
+
+
+def _validate_moderations_inputs(
+    start_time: int,
+    bucket_width: str,
+    end_time: int | None,
+    group_by: list[str] | None,
+    project_ids: list[str] | None,
+    user_ids: list[str] | None,
+    api_key_ids: list[str] | None,
+    models: list[str] | None,
+) -> None:
+    if not isinstance(start_time, int):
+        raise ValueError("`start_time` is required and must be a Unix timestamp in seconds.")
+
+    if bucket_width not in ALLOWED_COMPLETIONS_BUCKET_WIDTH:
+        raise ValueError("`bucket_width` supports only `1m`, `1h`, or `1d`.")
+
+    if end_time is not None and not isinstance(end_time, int):
+        raise ValueError("`end_time` must be a Unix timestamp in seconds.")
+
+    if group_by is not None:
+        if not isinstance(group_by, list):
+            raise ValueError("`group_by` must be an array.")
+        invalid = [value for value in group_by if value not in ALLOWED_MODERATIONS_GROUP_BY]
+        if invalid:
+            raise ValueError(
+                "`group_by` supports only project_id, user_id, api_key_id, model."
+            )
+
+    _validate_string_list(project_ids, "project_ids")
+    _validate_string_list(user_ids, "user_ids")
+    _validate_string_list(api_key_ids, "api_key_ids")
+    _validate_string_list(models, "models")
+
+
+def _validate_vector_stores_inputs(
+    start_time: int,
+    bucket_width: str,
+    end_time: int | None,
+    group_by: list[str] | None,
+    project_ids: list[str] | None,
+) -> None:
+    if not isinstance(start_time, int):
+        raise ValueError("`start_time` is required and must be a Unix timestamp in seconds.")
+
+    if bucket_width not in ALLOWED_COMPLETIONS_BUCKET_WIDTH:
+        raise ValueError("`bucket_width` supports only `1m`, `1h`, or `1d`.")
+
+    if end_time is not None and not isinstance(end_time, int):
+        raise ValueError("`end_time` must be a Unix timestamp in seconds.")
+
+    if group_by is not None:
+        if not isinstance(group_by, list):
+            raise ValueError("`group_by` must be an array.")
+        invalid = [value for value in group_by if value not in ALLOWED_VECTOR_STORES_GROUP_BY]
+        if invalid:
+            raise ValueError("`group_by` supports only `project_id`.")
+
+    _validate_string_list(project_ids, "project_ids")
+
+
+def _validate_users_inputs(emails: list[str] | None) -> None:
+    _validate_string_list(emails, "emails")
+
+
+def _validate_user_id(user_id: str) -> None:
+    if not isinstance(user_id, str) or not user_id.strip():
+        raise ValueError("`user_id` is required and must be a non-empty string.")
+
+
+def _validate_projects_inputs(include_archived: bool | None) -> None:
+    if include_archived is not None and not isinstance(include_archived, bool):
+        raise ValueError("`include_archived` must be a boolean.")
+
+
+def _get_admin_key() -> str:
+    admin_key = os.getenv("OPENAI_ADMIN_KEY") or os.getenv("OPENAI_API_KEY")
+    if not admin_key:
+        raise ValueError(
+            "Missing OPENAI_ADMIN_KEY (preferred) or OPENAI_API_KEY environment variable."
+        )
+    return admin_key
+
+
+async def _openai_get(url: str, query: dict[str, Any]) -> dict[str, Any]:
+    headers = {
+        "Authorization": f"Bearer {_get_admin_key()}",
+        "Content-Type": "application/json",
+    }
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        response = await client.get(url, params=query, headers=headers)
+        if response.is_error:
+            try:
+                error_payload = response.json()
+            except Exception:
+                error_payload = {"message": response.text}
+            raise RuntimeError(
+                f"OpenAI API error {response.status_code}: {error_payload}"
+            )
+        return response.json()
+
+
+async def _openai_get_all_pages(url: str, query: dict[str, Any]) -> dict[str, Any]:
+    """Fetch all paginated results and return merged data only."""
+    merged_data: list[dict[str, Any]] = []
+    current_query = dict(query)
+    seen_pages: set[str] = set()
+
+    while True:
+        payload = await _openai_get(url, current_query)
+        merged_data.extend(payload.get("data", []))
+
+        has_more = bool(payload.get("has_more"))
+        next_page = payload.get("next_page")
+        if not has_more or not next_page:
+            break
+        if next_page in seen_pages:
+            raise RuntimeError("Pagination loop detected from repeated `next_page` cursor.")
+        seen_pages.add(next_page)
+        current_query["page"] = next_page
+
+    return {"data": merged_data}
+
+
+async def _openai_get_all_after_pages(url: str, query: dict[str, Any]) -> dict[str, Any]:
+    """Fetch all `after` cursor paginated results and return merged data only."""
+    merged_data: list[dict[str, Any]] = []
+    current_query = dict(query)
+    seen_cursors: set[str] = set()
+
+    while True:
+        payload = await _openai_get(url, current_query)
+        merged_data.extend(payload.get("data", []))
+
+        has_more = bool(payload.get("has_more"))
+        last_id = payload.get("last_id")
+        if not has_more or not last_id:
+            break
+        if last_id in seen_cursors:
+            raise RuntimeError("Pagination loop detected from repeated `last_id` cursor.")
+        seen_cursors.add(last_id)
+        current_query["after"] = last_id
+
+    return {"data": merged_data}
+
+
+@mcp.tool()
+async def get_organization_costs(
+    start_time: int,
+    bucket_width: str = "1d",
+    end_time: int | None = None,
+    group_by: list[str] | None = None,
+    project_ids: list[str] | None = None,
+) -> dict[str, Any]:
+    """Get costs details for the organization via OpenAI Admin API.
+
+    Args:
+        start_time: Start time (Unix seconds), inclusive.
+        bucket_width: Bucket width. Currently only "1d" is supported.
+        end_time: End time (Unix seconds), exclusive.
+        group_by: Optional grouping keys. Allowed values: "project_id", "line_item". Example: ["project_id"], ["line_item"], ["project_id", "line_item"]
+        project_ids: Filter results to these OpenAI project IDs.
+    """
+    _validate_costs_inputs(start_time, bucket_width, end_time, group_by, project_ids)
+
+    query: dict[str, Any] = {
+        "start_time": start_time,
+        "bucket_width": bucket_width,
+    }
+    if end_time is not None:
+        query["end_time"] = end_time
+    if group_by:
+        query["group_by"] = group_by
+    if project_ids:
+        query["project_ids"] = project_ids
+
+    return await _openai_get_all_pages(OPENAI_COSTS_URL, query)
+
+
+@mcp.tool()
+async def get_organization_usage_completions(
+    start_time: int,
+    bucket_width: str = "1d",
+    end_time: int | None = None,
+    group_by: list[str] | None = None,
+    project_ids: list[str] | None = None,
+    user_ids: list[str] | None = None,
+    api_key_ids: list[str] | None = None,
+    models: list[str] | None = None,
+    batch: bool | None = None,
+) -> dict[str, Any]:
+    """Get completions usage details for the organization via OpenAI Admin API.
+
+    Args:
+        start_time: Start time (Unix seconds), inclusive.
+        bucket_width: Bucket width: "1m", "1h", or "1d" (default).
+        end_time: End time (Unix seconds), exclusive.
+        group_by: Optional grouping keys. Allowed values: "project_id", "user_id",
+            "api_key_id", "model", "batch", "service_tier". Any combination is allowed. Example: ["user_id"]
+        project_ids: Filter results by project IDs.
+        user_ids: Filter results by user IDs.
+        api_key_ids: Filter results by API key IDs.
+        models: Filter results by model names.
+        batch: If true, batch jobs only; if false, non-batch only.
+    """
+    _validate_completions_inputs(
+        start_time=start_time,
+        bucket_width=bucket_width,
+        end_time=end_time,
+        group_by=group_by,
+        project_ids=project_ids,
+        user_ids=user_ids,
+        api_key_ids=api_key_ids,
+        models=models,
+        batch=batch,
+    )
+
+    query: dict[str, Any] = {
+        "start_time": start_time,
+        "bucket_width": bucket_width,
+    }
+    if end_time is not None:
+        query["end_time"] = end_time
+    if group_by:
+        query["group_by"] = group_by
+    if project_ids:
+        query["project_ids"] = project_ids
+    if user_ids:
+        query["user_ids"] = user_ids
+    if api_key_ids:
+        query["api_key_ids"] = api_key_ids
+    if models:
+        query["models"] = models
+    if batch is not None:
+        query["batch"] = batch
+
+    return await _openai_get_all_pages(OPENAI_USAGE_COMPLETIONS_URL, query)
+
+
+@mcp.tool()
+async def get_organization_usage_audio_speeches(
+    start_time: int,
+    bucket_width: str = "1d",
+    end_time: int | None = None,
+    group_by: list[str] | None = None,
+    project_ids: list[str] | None = None,
+    user_ids: list[str] | None = None,
+    api_key_ids: list[str] | None = None,
+    models: list[str] | None = None,
+) -> dict[str, Any]:
+    """Get audio speeches usage details for the organization via OpenAI Admin API.
+
+    Args:
+        start_time: Start time (Unix seconds), inclusive.
+        bucket_width: Bucket width: "1m", "1h", or "1d" (default).
+        end_time: End time (Unix seconds), exclusive.
+        group_by: Optional grouping keys. Allowed values: "project_id", "user_id",
+            "api_key_id", "model". Any combination is allowed. Example: ["user_id"]
+        project_ids: Filter results by project IDs.
+        user_ids: Filter results by user IDs.
+        api_key_ids: Filter results by API key IDs.
+        models: Filter results by model names.
+    """
+    _validate_audio_speeches_inputs(
+        start_time=start_time,
+        bucket_width=bucket_width,
+        end_time=end_time,
+        group_by=group_by,
+        project_ids=project_ids,
+        user_ids=user_ids,
+        api_key_ids=api_key_ids,
+        models=models,
+    )
+
+    query: dict[str, Any] = {
+        "start_time": start_time,
+        "bucket_width": bucket_width,
+    }
+    if end_time is not None:
+        query["end_time"] = end_time
+    if group_by:
+        query["group_by"] = group_by
+    if project_ids:
+        query["project_ids"] = project_ids
+    if user_ids:
+        query["user_ids"] = user_ids
+    if api_key_ids:
+        query["api_key_ids"] = api_key_ids
+    if models:
+        query["models"] = models
+
+    return await _openai_get_all_pages(OPENAI_USAGE_AUDIO_SPEECHES_URL, query)
+
+
+@mcp.tool()
+async def get_organization_usage_audio_transcriptions(
+    start_time: int,
+    bucket_width: str = "1d",
+    end_time: int | None = None,
+    group_by: list[str] | None = None,
+    project_ids: list[str] | None = None,
+    user_ids: list[str] | None = None,
+    api_key_ids: list[str] | None = None,
+    models: list[str] | None = None,
+) -> dict[str, Any]:
+    """Get audio transcriptions usage details for the organization via OpenAI Admin API.
+
+    Args:
+        start_time: Start time (Unix seconds), inclusive.
+        bucket_width: Bucket width: "1m", "1h", or "1d" (default).
+        end_time: End time (Unix seconds), exclusive.
+        group_by: Optional grouping keys. Allowed values: "project_id", "user_id",
+            "api_key_id", "model". Any combination is allowed. Example: ["user_id"]
+        project_ids: Filter results by project IDs.
+        user_ids: Filter results by user IDs.
+        api_key_ids: Filter results by API key IDs.
+        models: Filter results by model names.
+    """
+    _validate_audio_transcriptions_inputs(
+        start_time=start_time,
+        bucket_width=bucket_width,
+        end_time=end_time,
+        group_by=group_by,
+        project_ids=project_ids,
+        user_ids=user_ids,
+        api_key_ids=api_key_ids,
+        models=models,
+    )
+
+    query: dict[str, Any] = {
+        "start_time": start_time,
+        "bucket_width": bucket_width,
+    }
+    if end_time is not None:
+        query["end_time"] = end_time
+    if group_by:
+        query["group_by"] = group_by
+    if project_ids:
+        query["project_ids"] = project_ids
+    if user_ids:
+        query["user_ids"] = user_ids
+    if api_key_ids:
+        query["api_key_ids"] = api_key_ids
+    if models:
+        query["models"] = models
+
+    return await _openai_get_all_pages(OPENAI_USAGE_AUDIO_TRANSCRIPTIONS_URL, query)
+
+
+@mcp.tool()
+async def get_organization_usage_code_interpreter_sessions(
+    start_time: int,
+    bucket_width: str = "1d",
+    end_time: int | None = None,
+    group_by: list[str] | None = None,
+    project_ids: list[str] | None = None,
+) -> dict[str, Any]:
+    """Get code interpreter sessions usage details for the organization via OpenAI Admin API.
+
+    Args:
+        start_time: Start time (Unix seconds), inclusive.
+        bucket_width: Bucket width: "1m", "1h", or "1d" (default).
+        end_time: End time (Unix seconds), exclusive.
+        group_by: Optional grouping keys. Only "project_id" is allowed. Example: ["project_id"]
+        project_ids: Filter results by project IDs.
+    """
+    _validate_code_interpreter_sessions_inputs(
+        start_time=start_time,
+        bucket_width=bucket_width,
+        end_time=end_time,
+        group_by=group_by,
+        project_ids=project_ids,
+    )
+
+    query: dict[str, Any] = {
+        "start_time": start_time,
+        "bucket_width": bucket_width,
+    }
+    if end_time is not None:
+        query["end_time"] = end_time
+    if group_by:
+        query["group_by"] = group_by
+    if project_ids:
+        query["project_ids"] = project_ids
+
+    return await _openai_get_all_pages(OPENAI_USAGE_CODE_INTERPRETER_SESSIONS_URL, query)
+
+
+@mcp.tool()
+async def get_organization_usage_embeddings(
+    start_time: int,
+    bucket_width: str = "1d",
+    end_time: int | None = None,
+    group_by: list[str] | None = None,
+    project_ids: list[str] | None = None,
+    user_ids: list[str] | None = None,
+    api_key_ids: list[str] | None = None,
+    models: list[str] | None = None,
+) -> dict[str, Any]:
+    """Get embeddings usage details for the organization via OpenAI Admin API.
+
+    Args:
+        start_time: Start time (Unix seconds), inclusive.
+        bucket_width: Bucket width: "1m", "1h", or "1d" (default).
+        end_time: End time (Unix seconds), exclusive.
+        group_by: Optional grouping keys. Allowed values: "project_id", "user_id",
+            "api_key_id", "model". Any combination is allowed. Example: ["user_id"].
+        project_ids: Filter results by project IDs.
+        user_ids: Filter results by user IDs.
+        api_key_ids: Filter results by API key IDs.
+        models: Filter results by model names.
+    """
+    _validate_embeddings_inputs(
+        start_time=start_time,
+        bucket_width=bucket_width,
+        end_time=end_time,
+        group_by=group_by,
+        project_ids=project_ids,
+        user_ids=user_ids,
+        api_key_ids=api_key_ids,
+        models=models,
+    )
+
+    query: dict[str, Any] = {
+        "start_time": start_time,
+        "bucket_width": bucket_width,
+    }
+    if end_time is not None:
+        query["end_time"] = end_time
+    if group_by:
+        query["group_by"] = group_by
+    if project_ids:
+        query["project_ids"] = project_ids
+    if user_ids:
+        query["user_ids"] = user_ids
+    if api_key_ids:
+        query["api_key_ids"] = api_key_ids
+    if models:
+        query["models"] = models
+
+    return await _openai_get_all_pages(OPENAI_USAGE_EMBEDDINGS_URL, query)
+
+
+@mcp.tool()
+async def get_organization_usage_images(
+    start_time: int,
+    bucket_width: str = "1d",
+    end_time: int | None = None,
+    group_by: list[str] | None = None,
+    project_ids: list[str] | None = None,
+    user_ids: list[str] | None = None,
+    api_key_ids: list[str] | None = None,
+    models: list[str] | None = None,
+    sizes: list[str] | None = None,
+    sources: list[str] | None = None,
+) -> dict[str, Any]:
+    """Get images usage details for the organization via OpenAI Admin API.
+
+    Args:
+        start_time: Start time (Unix seconds), inclusive.
+        bucket_width: Bucket width: "1m", "1h", or "1d" (default).
+        end_time: End time (Unix seconds), exclusive.
+        group_by: Optional grouping keys. Allowed values: "project_id", "user_id",
+            "api_key_id", "model", "size", "source". Any combination is allowed. Example: ["user_id"]
+        project_ids: Filter results by project IDs.
+        user_ids: Filter results by user IDs.
+        api_key_ids: Filter results by API key IDs.
+        models: Filter results by model names.
+        sizes: Filter by image sizes. Allowed values: "256x256", "512x512", "1024x1024",
+            "1792x1792", "1024x1792".
+        sources: Filter by image source types. Allowed values: "image.generation",
+            "image.edit", "image.variation".
+    """
+    _validate_images_inputs(
+        start_time=start_time,
+        bucket_width=bucket_width,
+        end_time=end_time,
+        group_by=group_by,
+        project_ids=project_ids,
+        user_ids=user_ids,
+        api_key_ids=api_key_ids,
+        models=models,
+        sizes=sizes,
+        sources=sources,
+    )
+
+    query: dict[str, Any] = {
+        "start_time": start_time,
+        "bucket_width": bucket_width,
+    }
+    if end_time is not None:
+        query["end_time"] = end_time
+    if group_by:
+        query["group_by"] = group_by
+    if project_ids:
+        query["project_ids"] = project_ids
+    if user_ids:
+        query["user_ids"] = user_ids
+    if api_key_ids:
+        query["api_key_ids"] = api_key_ids
+    if models:
+        query["models"] = models
+    if sizes:
+        query["sizes"] = sizes
+    if sources:
+        query["sources"] = sources
+
+    return await _openai_get_all_pages(OPENAI_USAGE_IMAGES_URL, query)
+
+
+@mcp.tool()
+async def get_organization_usage_moderations(
+    start_time: int,
+    bucket_width: str = "1d",
+    end_time: int | None = None,
+    group_by: list[str] | None = None,
+    project_ids: list[str] | None = None,
+    user_ids: list[str] | None = None,
+    api_key_ids: list[str] | None = None,
+    models: list[str] | None = None,
+) -> dict[str, Any]:
+    """Get moderations usage details for the organization via OpenAI Admin API.
+
+    Args:
+        start_time: Start time (Unix seconds), inclusive.
+        bucket_width: Bucket width: "1m", "1h", or "1d" (default).
+        end_time: End time (Unix seconds), exclusive.
+        group_by: Optional grouping keys. Allowed values: "project_id", "user_id",
+            "api_key_id", "model". Any combination is allowed. Example: ["project_id"]
+        project_ids: Filter results by project IDs.
+        user_ids: Filter results by user IDs.
+        api_key_ids: Filter results by API key IDs.
+        models: Filter results by model names.
+    """
+    _validate_moderations_inputs(
+        start_time=start_time,
+        bucket_width=bucket_width,
+        end_time=end_time,
+        group_by=group_by,
+        project_ids=project_ids,
+        user_ids=user_ids,
+        api_key_ids=api_key_ids,
+        models=models,
+    )
+
+    query: dict[str, Any] = {
+        "start_time": start_time,
+        "bucket_width": bucket_width,
+    }
+    if end_time is not None:
+        query["end_time"] = end_time
+    if group_by:
+        query["group_by"] = group_by
+    if project_ids:
+        query["project_ids"] = project_ids
+    if user_ids:
+        query["user_ids"] = user_ids
+    if api_key_ids:
+        query["api_key_ids"] = api_key_ids
+    if models:
+        query["models"] = models
+
+    return await _openai_get_all_pages(OPENAI_USAGE_MODERATIONS_URL, query)
+
+
+@mcp.tool()
+async def get_organization_usage_vector_stores(
+    start_time: int,
+    bucket_width: str = "1d",
+    end_time: int | None = None,
+    group_by: list[str] | None = None,
+    project_ids: list[str] | None = None,
+) -> dict[str, Any]:
+    """Get vector stores usage details for the organization via OpenAI Admin API.
+
+    Args:
+        start_time: Start time (Unix seconds), inclusive.
+        bucket_width: Bucket width: "1m", "1h", or "1d" (default).
+        end_time: End time (Unix seconds), exclusive.
+        group_by: Optional grouping keys. Only "project_id" is allowed. Example: ["project_id"]
+        project_ids: Filter results by project IDs.
+    """
+    _validate_vector_stores_inputs(
+        start_time=start_time,
+        bucket_width=bucket_width,
+        end_time=end_time,
+        group_by=group_by,
+        project_ids=project_ids,
+    )
+
+    query: dict[str, Any] = {
+        "start_time": start_time,
+        "bucket_width": bucket_width,
+    }
+    if end_time is not None:
+        query["end_time"] = end_time
+    if group_by:
+        query["group_by"] = group_by
+    if project_ids:
+        query["project_ids"] = project_ids
+
+    return await _openai_get_all_pages(OPENAI_USAGE_VECTOR_STORES_URL, query)
+
+
+@mcp.tool()
+async def get_organization_users(
+    emails: list[str] | None = None,
+) -> dict[str, Any]:
+    """List all organization users via OpenAI Admin API.
+
+    Args:
+        emails: Optional list of email addresses to filter users. Example: ["user1@example.com", "user2@example.com"]
+    """
+    _validate_users_inputs(emails)
+
+    query: dict[str, Any] = {}
+    if emails:
+        query["emails"] = emails
+
+    return await _openai_get_all_after_pages(OPENAI_ORGANIZATION_USERS_URL, query)
+
+
+@mcp.tool()
+async def get_organization_user(
+    user_id: str,
+) -> dict[str, Any]:
+    """Retrieve a single organization user by ID via OpenAI Admin API.
+
+    Args:
+        user_id: The organization user identifier.
+    """
+    _validate_user_id(user_id)
+
+    return await _openai_get(f"{OPENAI_ORGANIZATION_USERS_URL}/{user_id}", {})
+
+
+@mcp.tool()
+async def get_organization_projects(
+    include_archived: bool | None = None,
+) -> dict[str, Any]:
+    """List all organization projects via OpenAI Admin API.
+
+    Args:
+        include_archived: If true, include archived projects.
+    """
+    _validate_projects_inputs(include_archived)
+
+    query: dict[str, Any] = {}
+    if include_archived is not None:
+        query["include_archived"] = include_archived
+
+    return await _openai_get_all_after_pages(OPENAI_ORGANIZATION_PROJECTS_URL, query)
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

openai_admin_usage_mcp_server-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+