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

> Learn the recommended approach for testing the MCP server locally using Vitest, MCP Inspector, and real clients for comprehensive validation. Explore the flux159/mcp-server-kubernetes repository.

- Repository: [Suyog Sonwalkar/mcp-server-kubernetes](https://github.com/flux159/mcp-server-kubernetes)
- Tags: testing
- Published: 2026-03-02

---

**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:

```bash
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:

```bash
bun run dev

```

This monitors [`src/index.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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:

```bash
bun run test

```

The test definitions reside in `tests/`, with [`tests/kubernetes-manager.test.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/tests/kubernetes-manager.test.ts) specifically validating that [`src/utils/kubernetes-manager.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/utils/kubernetes-manager.ts) correctly loads kubeconfig contexts and handles API interactions. Unit tests for individual tools (such as [`kubectl-get.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/kubectl-get.ts) or [`helm-operations.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/helm-operations.ts) in `src/tools/`) verify argument parsing and response formatting in isolation.

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

```bash
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:

```bash
bun run build

```

This generates [`dist/index.js`](https://github.com/flux159/mcp-server-kubernetes/blob/main/dist/index.js), the compiled entry point. Launch the inspector against this artifact:

```bash
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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/index.ts) correctly handles the `ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS` restriction.

For detailed tracing during inspector sessions, enable OpenTelemetry:

```bash
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:

```bash
ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true bun run start

```

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

```bash
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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-get.ts) or kubeconfig loading in [`src/utils/kubernetes-manager.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/utils/kubernetes-manager.ts). The **MCP Inspector** (`npx @modelcontextprotocol/inspector`) validates the compiled server binary ([`dist/index.js`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/index.ts) and its dependencies into [`dist/index.js`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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.