k8s-mcp-server

k8s-mcp-server

An MCP server that enables natural language querying and troubleshooting of Kubernetes clusters, supporting multi-cluster switching and providing tools for pods, nodes, events, and logs.

Category
Visit Server

README

k8s-mcp-server

一个基于 MCP（Model Context Protocol） 的 Kubernetes 运维助手。它将 K8s 集群的查询能力封装成标准化的 MCP 工具，让 LLM 客户端（如 ZCode、Claude Desktop、Cursor）能够通过自然语言查看和排查 Kubernetes 集群。

功能特性

  • 基于 MCP Python SDK，使用 stdio 传输
  • 支持多集群切换（本地 k3s / 阿里云 k3s）
  • 完善的异常处理，错误信息对 LLM 友好
  • 输出经过精简格式化，避免返回冗余的 K8s 原始对象

工具列表

工具 说明
ping 健康检查，返回 pong
list_namespaces 列出所有 namespace 及其状态
list_pods 列出指定 namespace 下的 Pod
describe_pod 查看 Pod 详情（状态、IP、节点、容器、重启次数、资源）
get_pod_logs 获取 Pod 日志（支持 tail_lines 限制行数）
list_nodes 列出集群节点及状态、OS、K8s 版本
list_events 列出所有 namespace 的最近事件（按时间倒序）

环境要求

  • Python 3.12+
  • uv 包管理器
  • 可访问的 Kubernetes 集群及对应的 kubeconfig

安装

git clone git@github.com:AmazingYe-oss/k8s-mcp-server.git
cd k8s-mcp-server
uv sync

配置

默认从以下路径加载 kubeconfig（在 src/k8s_mcp_server/k8s_client.py 中配置）：

  • local → ~/.kube/config
  • cloud → ~/.kube/config-k3s-cloud

如需修改集群映射，编辑 KUBECONFIGS 字典即可。

运行

uv run k8s-mcp-server

服务器以 stdio 模式启动，等待 MCP 客户端连接。

MCP 客户端配置

ZCode / Claude Desktop（Windows 连接 WSL 中的 Server）

{
  "mcp": {
    "servers": {
      "k8s": {
        "type": "stdio",
        "command": "wsl",
        "args": [
          "bash",
          "-lc",
          "cd /home/<your-user>/k8s-mcp-server && uv run k8s-mcp-server"
        ]
      }
    }
  }
}

原生 Linux/macOS

{
  "mcp": {
    "servers": {
      "k8s": {
        "type": "stdio",
        "command": "uv",
        "args": ["--directory", "/path/to/k8s-mcp-server", "run", "k8s-mcp-server"]
      }
    }
  }
}

项目结构

src/k8s_mcp_server/
├── __init__.py
├── server.py        # MCP Server 入口，注册工具
├── k8s_client.py    # K8s API 客户端封装与异常处理
└── formatters.py    # K8s 对象到精简文本的格式化

开发

# 代码检查
uv run ruff check .

# 运行测试
uv run pytest

Recommended Servers

playwright-mcp

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official
Featured
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Official
Featured
Local
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

Official
Featured
Local
TypeScript
VeyraX MCP

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official
Featured
Local
graphlit-mcp-server

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official
Featured
TypeScript
Kagi MCP Server

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official
Featured
Python
Neon Database

Neon Database

MCP server for interacting with Neon Management API and databases

Official
Featured
E2B

E2B

Using MCP to run code via e2b.

Official
Featured
Exa Search

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official
Featured
Qdrant Server

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official
Featured