Recommended Approach for Testing the MCP Server Locally: A Complete Guide

The recommended approach for testing the MCP server locally involves a layered validation strategy: execute the Vitest unit and integration suite, validate protocol compliance using the MCP Inspector, and perform end-to-end verification with real clients like Claude Desktop or mcp-chat, always operating in non-destructive mode.

The flux159/mcp-server-kubernetes repository provides a TypeScript-based Model Context Protocol (MCP) server that enables LLMs to interact with Kubernetes clusters via tools like kubectl_get and helm_install. Following the recommended approach for testing the MCP server locally ensures that modifications to tool handlers in src/tools/ or the KubernetesManager class do not introduce regressions while preventing accidental modifications to live cluster state.

Setting Up the Development Environment

Before executing tests, configure the runtime environment. The project uses Bun as its JavaScript runtime and package manager.

Clone the repository and install dependencies:

git clone https://github.com/Flux159/mcp-server-kubernetes.git
cd mcp-server-kubernetes
bun install

For active development, use the watch mode to recompile TypeScript on file changes:

bun run dev

This monitors src/index.ts (the server entry point) and all tool implementations under src/tools/, emitting compiled JavaScript to the dist/ directory.

Layer 1: Unit and Integration Testing with Vitest

The fastest feedback loop comes from the comprehensive Vitest test suite. These tests exercise individual tool logic and the KubernetesManager without requiring a full client connection.

Execute the full suite:

bun run test

The test definitions reside in tests/, with tests/kubernetes-manager.test.ts specifically validating that src/utils/kubernetes-manager.ts correctly loads kubeconfig contexts and handles API interactions. Unit tests for individual tools (such as kubectl-get.ts or helm-operations.ts in src/tools/) verify argument parsing and response formatting in isolation.

Always run tests with the non-destructive safety flag enabled:

ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true bun run test

This environment variable prevents test suites from invoking tools that delete or modify cluster resources, ensuring that even integration tests against live clusters remain safe.

Layer 2: Protocol Validation with the MCP Inspector

After unit tests pass, validate that the compiled server adheres to the MCP protocol specification using the MCP Inspector. This tool launches the server binary and exposes a web interface for exercising tools and resources.

First, build the production bundle:

bun run build

This generates dist/index.js, the compiled entry point. Launch the inspector against this artifact:

npx @modelcontextprotocol/inspector node dist/index.js

The inspector opens a temporary web UI where you can invoke tools (e.g., kubectl_get or kubectl_logs) and inspect raw protocol messages. This validates the transport layer (StdIO or Server-Sent Events) and ensures that tool filtering logic in src/index.ts correctly handles the ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS restriction.

For detailed tracing during inspector sessions, enable OpenTelemetry:

ENABLE_TELEMETRY=true npx @modelcontextprotocol/inspector node dist/index.js

This emits spans for each Kubernetes API call, visible in the inspector's tracing panel, helping diagnose latency issues in KubernetesManager methods.

Layer 3: End-to-End Testing with Real Clients

The final validation layer involves connecting the server to actual MCP clients to verify real-world behavior. This confirms that tool responses render correctly in conversational interfaces and that the server handles concurrent requests properly.

Start the server in non-destructive mode:

ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true bun run start

In a separate terminal, connect using the mcp-chat CLI:

npx mcp-chat --server "npx mcp-server-kubernetes"

Alternatively, configure Claude Desktop to point at your local build by editing its configuration to reference node /path/to/dist/index.js. Interact with the cluster using natural language requests (e.g., "List pods in the default namespace") to verify that src/tools/kubectl-get.ts correctly parses arguments and returns formatted resource lists.

This end-to-end validation catches issues that unit tests miss, such as JSON serialization errors in tool responses or subtle bugs in the KubernetesManager connection pooling when handling multiple simultaneous kubectl_logs requests.

Summary

• Install dependencies with bun install and use bun run dev for watch-mode development.
• Execute Vitest suites via bun run test to validate logic in src/tools/ and src/utils/kubernetes-manager.ts.
• Enable non-destructive mode by setting ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true to prevent accidental cluster modifications during all testing phases.
• Validate protocol compliance using npx @modelcontextprotocol/inspector against the compiled dist/index.js.
• Perform final verification by connecting mcp-chat or Claude Desktop to the running server to confirm real-world tool execution.

Frequently Asked Questions

How do I run tests without modifying my Kubernetes cluster?

Set the ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS environment variable to true before executing any test command. This flag filters the available tools in src/index.ts to exclude destructive operations like kubectl_delete or helm_uninstall, ensuring that both Vitest suites and manual inspector sessions can only read or list resources.

What is the difference between the MCP Inspector and running unit tests?

Unit tests executed via bun run test validate individual functions in isolation, such as argument parsing in src/tools/kubectl-get.ts or kubeconfig loading in src/utils/kubernetes-manager.ts. The MCP Inspector (npx @modelcontextprotocol/inspector) validates the compiled server binary (dist/index.js) as a black box, testing the actual transport layer, protocol handshake, and tool invocation over StdIO or SSE, which catches integration issues that unit tests cannot.

Can I test the server without installing Claude Desktop?

Yes. While Claude Desktop provides a graphical interface for end-to-end testing, you can achieve similar validation using the mcp-chat CLI. After starting the server with bun run start, run npx mcp-chat --server "npx mcp-server-kubernetes" to interact with the tools via command line, verifying that kubectl_get and other operations return correctly formatted responses without requiring a desktop application.

Why must I build the project before using the Inspector?

The MCP Inspector executes the compiled JavaScript output rather than the TypeScript source. Running bun run build transpiles src/index.ts and its dependencies into dist/index.js, ensuring that the inspector tests the exact artifact that would run in production. Attempting to point the inspector at uncompiled TypeScript files will result in execution errors or protocol mismatches.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}