Kubernetes Tools MCP Server

Instructions

Parameters
----------
None
    This function does not take any parameters.

Returns
-------
list of NamespaceSummary
    List of namespace summary objects. Each NamespaceSummary has the following fields:

    name : str
        Name of the namespace.
    status : str
        Status phase of the namespace.
    age : datetime.timedelta
        Age of the namespace (current time minus creation timestamp).
Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list namespaces fails.

Implementation Reference

• src/k8stools/k8s_tools.py:79-117 (handler)

  The handler function implementing the core logic of the get_namespaces tool. It uses the Kubernetes CoreV1Api to list namespaces, calculates their age, and returns a list of NamespaceSummary pydantic models.

  def get_namespaces() -> list[NamespaceSummary]:
      """Return a summary of the namespaces for this Kubernetes cluster, similar to that
      returned by `kubectl get namespace`.
  
      Parameters
      ----------
      None
          This function does not take any parameters.
  
      Returns
      -------
      list of NamespaceSummary
          List of namespace summary objects. Each NamespaceSummary has the following fields:
  
          name : str
              Name of the namespace.
          status : str
              Status phase of the namespace.
          age : datetime.timedelta
              Age of the namespace (current time minus creation timestamp).
      Raises
      ------
      K8sConfigError
          If unable to initialize the K8S API.
      K8sApiError
          If the API call to list namespaces fails.
      """
      global K8S
      if K8S is None:
          K8S = _get_api_client()
      logging.info(f"get_namespaces()")
      namespaces = K8S.list_namespace().items
      now = datetime.datetime.now(datetime.timezone.utc)
      return [
          NamespaceSummary(name=namespace.metadata.name,
                          status=namespace.status.phase,
                          age=now-namespace.metadata.creation_timestamp)
          for namespace in namespaces
      ]

• src/k8stools/k8s_tools.py:72-77 (schema)

  Pydantic model defining the output schema for each namespace returned by get_namespaces.

  class NamespaceSummary(BaseModel):
      """Summary information about a namespace, like returned by `kubectl get namespace`"""
      name: str
      status: str
      age: datetime.timedelta

• src/k8stools/mcp_server.py:46-65 (registration)

  Code in the MCP server that imports the TOOLS list (including get_namespaces) from k8s_tools or mock_tools, wraps each function into a FastMCP Tool object, and registers them in the FastMCP server instance.

  if not args.mock:
      from .k8s_tools import TOOLS
  else:
      from .mock_tools import TOOLS
      logging.warning(f"Using mock versions of the tools")
  wrapped_tools = [get_tool_for_function(fn) for fn in TOOLS]
  
  mcp = FastMCP(
      name="k8stools-"+args.transport,
      tools=wrapped_tools,
      streamable_http_path="/mcp",
      stateless_http=(args.transport == 'streamable-http'),
      host=args.host,
      port=args.port,
      log_level=args.log_level,
      debug=args.debug
  )
  logging.debug(f"Settings are: {mcp.settings}")
  logging.info(f"Starting with {len(wrapped_tools)} tools on transport {args.transport}")
  # this starts the uvicorn server

• src/k8stools/k8s_tools.py:1101-1111 (registration)

  The TOOLS list that collects all tool handler functions, including get_namespaces, for use in MCP server registration.

  TOOLS = [
      get_namespaces,
      get_node_summaries,
      get_pod_summaries,
      get_pod_container_statuses,
      get_pod_events,
      get_pod_spec,
      get_logs_for_pod_and_container,
      get_deployment_summaries,
      get_service_summaries
  ]

• src/k8stools/mcp_server.py:22-26 (helper)

  Helper function that converts a tool handler function into an MCP-compatible Tool object using FastMCP's Tool.from_function, enabling schema inference and structured output.

  def get_tool_for_function(fn) -> Tool:
      tool = Tool.from_function(fn, structured_output=True)
      #return_type = fn.__annotations__['return']
      return tool