Skip to main content
Glama
Sign In
YuniKorn MCP Server

YuniKorn MCP Server

by frenoid
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

YuniKorn MCP Server

A Model Context Protocol (MCP) server that interfaces with the Apache YuniKorn Scheduler, allowing AI agents to observe and reason about Kubernetes batch workload resource management, queue hierarchies, and application states.

Screenshots

Inspecting Yunikorn tools using MCP inspector get_partition_queues in MCP inspector

Querying the Yunikorn scheduler via MCP using Opencode Querying Yunikorn scheduler information in Opencode

Related MCP server: Kubectl MCP Tool

Features

  • 7 MCP Tools: Query partitions, queues, applications, nodes, user usage, and scheduler health

  • 2 MCP Resources: Static data access for partitions list and node utilization

  • Async HTTP: Non-blocking API calls using httpx

  • Proper Error Mapping: YuniKorn HTTP errors mapped to standard MCP error responses

  • Resource Awareness: Handles YuniKorn's raw bytes and millicore values

  • CORS Enabled: Allows connections from any origin for browser-based MCP Inspector

  • Streamable HTTP: Default transport with stdio fallback for IDE integration

Installation

uv pip install -r requirements.txt

If you are using a virtual environment, make sure it is activated first:

source .venv/bin/activate
uv pip install -r requirements.txt

Usage

Running the Server

The default transport is Streamable HTTP on port 8000:

Run locally

uv run python -m main

Run with Docker

docker run -p 8000:8000 -e YUNIKORN_BASE_URL="http://<REPLACE_ME>/ws/v1" docker.io/frenoid/yunikorn-mcp-server:latest

Command line options

Option

Description

Default

--transport

Transport protocol (stdio, streamable-http)

streamable-http

--host

Host to bind (HTTP transport only)

0.0.0.0

--port

Port to listen on (HTTP transport only)

8000

--log-level

Logging level

INFO

Examples:

# Streamable HTTP on custom port
uv run python -m main --transport streamable-http --host 127.0.0.1 --port 8080

# Stdio mode for Claude Code / IDE integration
uv run python -m main --transport stdio

Environment Variables

Variable

Description

Default

YUNIKORN_BASE_URL

Base URL of the YuniKorn REST API

http://localhost:9089/ws/v1/

TLS_INSECURE

Disable HTTPS certificate verification (true/false)

false

# Connect to a remote YuniKorn instance
YUNIKORN_BASE_URL=http://yunikorn.example.com:9089/ws/v1/ uv run python -m main

# Connect to an HTTPS endpoint with a self-signed certificate
YUNIKORN_BASE_URL=https://yunikorn.example.com:9089/ws/v1/ TLS_INSECURE=true uv run python -m main

Connecting with MCP Inspector

The Streamable HTTP endpoint is exposed at the /mcp path:

http://localhost:8000/mcp

Testing

Run the test suite against a live YuniKorn instance:

YUNIKORN_BASE_URL=http://your-yunikorn-host:9089/ws/v1/ uv run python test_server.py

To run a quick compliance check:

YUNIKORN_BASE_URL=http://your-yunikorn-host:9089/ws/v1/ uv run python test_updated_server.py

Data Format Notes

  • Memory: Represented in raw bytes (64-bit signed integers).

  • CPU (vcore): Represented in millicores (thousandths of a core, i.e. 1000m = 1 core).

  • Other resources: No specific unit assigned.

  • Active applications: The virtual "active" state represents New, Accepted, Running, Completing, and Failing statuses.

  • allocationID vs uuid: uuid is deprecated. allocationID contains the same base value as uuid with a hyphen-counter suffix (e.g., -0, -1).

  • allocationDelay: The difference between allocationTime and requestTime for an allocation.

API Conformance

This MCP server conforms to the Apache YuniKorn Scheduler REST API (v1.8.0). Each tool maps directly to a documented endpoint.

Tool

YuniKorn Endpoint

get_partitions

GET /ws/v1/partitions

get_partition_queues

GET /ws/v1/partition/{partitionName}/queues

get_applications_by_state

GET /ws/v1/partition/{partitionName}/applications/{state}?status={status}

inspect_application

GET /ws/v1/partition/{partitionName}/application/{appId}

get_node_details

GET /ws/v1/partition/{partitionName}/nodes or /node/{nodeId}

get_user_usage

GET /ws/v1/partition/{partitionName}/usage/users or /usage/user/{userName}

check_scheduler_health

GET /ws/v1/scheduler/healthcheck

Resources:

Resource

YuniKorn Endpoint

yunikorn://partitions/list

GET /ws/v1/partitions

yunikorn://nodes/utilization

GET /ws/v1/scheduler/node-utilizations

Error Mapping

YuniKorn HTTP Code

MCP Error

400 Bad Request

INVALID_REQUEST

404 Not Found

INVALID_REQUEST

500 Internal Server Error

INTERNAL_ERROR

Available Tools

7 tools
check_scheduler_healthA

Returns the health status of the scheduler, checking for critical logs and negative resource values. IMPORTANT: resource values are raw integers (bytes for memory, millicores for CPU). Convert these to human-readable formats (e.g., GiB or Cores) before presenting to the user.

Inputs: no named parameters. Returns: result

get_applications_by_stateA

Retrieves applications filtered by their current lifecycle state (active, rejected, or completed). Active is a virtual state representing New, Accepted, Running, Completing, or Failing apps. When state is 'active', you can optionally set status to new, accepted, running, completing, or failing (case-insensitive) to narrow results. Defaults to running if not specified. IMPORTANT: resource values are raw integers (bytes for memory, millicores for CPU). Convert these to human-readable formats (e.g., GiB or Cores) before presenting to the user.

Inputs: state (required), partitionName (required), status. Returns: result

get_node_detailsA

Fetches all nodes or a specific node managed by YuniKorn, including capacity and utilization percentages. IMPORTANT: resource values are raw integers (bytes for memory, millicores for CPU). Convert these to human-readable formats (e.g., GiB or Cores) before presenting to the user.

Inputs: partitionName (required), nodeId. Returns: result

get_partition_queuesA

Fetches the full queue hierarchy for a specific partition. Includes maxResource, guaranteedResource, and pendingResource for each queue. IMPORTANT: resource values are raw integers (bytes for memory, millicores for CPU). Convert these to human-readable formats (e.g., GiB or Cores) before presenting to the user.

Inputs: partitionName (required). Returns: result

get_partitionsA

Retrieves general information and statistics for all partitions in the cluster. Useful for seeing total cluster capacity, used capacity, and node counts. IMPORTANT: resource values (memory, cpu) are returned as raw integers (bytes for memory, millicores for CPU). Convert these to human-readable formats (e.g., GiB or Cores) before presenting to the user.

Inputs: no named parameters. Returns: result

get_user_usageA

Retrieves resource usage and quota information for all users or a specific user. IMPORTANT: resource values are raw integers (bytes for memory, millicores for CPU). Convert these to human-readable formats (e.g., GiB or Cores) before presenting to the user.

Inputs: partitionName (required), userName. Returns: result

inspect_applicationA

Provides detailed metadata for a single application, including its allocation log and resource requests. Both uuid (deprecated) and allocationID fields may appear in allocations; allocationID contains the same base value as uuid plus a hyphen-counter suffix (e.g., -0, -1). Use allocationID to identify specific task allocations. IMPORTANT: resource values are raw integers (bytes for memory, millicores for CPU). Convert these to human-readable formats (e.g., GiB or Cores) before presenting to the user.

Inputs: appId (required), partitionName (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct domain entity: partitions, partition queues, applications, individual application details, nodes, user usage, and scheduler health. There is no overlap in purpose, making selection unambiguous.

    Naming Consistency5/5

    All tool names follow a clear verb_noun pattern (get_partitions, get_partition_queues, get_applications_by_state, inspect_application, get_node_details, get_user_usage, check_scheduler_health). The pattern is consistent and predictable.

    Tool Count5/5

    With 7 tools, the server is well-scoped for its purpose of monitoring and querying a YuniKorn cluster. Each tool covers a necessary aspect without unnecessary bloat.

    Completeness4/5

    The tool set covers the core query surfaces: partitions, queues, applications, nodes, user usage, and health. Minor gaps exist (e.g., no scheduler configuration or historical metrics retrieval), but the primary workflows are fully supported.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • kube-mcp

      lochgeo
      A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables interaction with Kubernetes/Minikube clusters through natural language, allowing AI agents like Codename Goose to manage Kubernetes resources via the Model Context Protocol.
      2
      MIT

    • Kubectl MCP Tool

      rohitg00
      A
      license
      Not graded
      quality
      C
      maintenance
      A Model Context Protocol server that enables AI assistants to interact with Kubernetes clusters through natural language, supporting core Kubernetes operations, monitoring, security, and diagnostics.
      169 npm
      972
      MIT

    • K8s_MCP

      Dousery
      F
      license
      Not graded
      quality
      D
      maintenance
      An Model Context Protocol server that lets language models directly manage and visualize Kubernetes clusters through safe, high-level operational tools.
      1
      -