Skip to content

Update README #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 30, 2025
+92 −42
Merged

Update README #60

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 92 additions & 42 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@
<img src="docs/assets/mkp-logo.png" width="400" alt="MKP Logo">
</p>

MKP is a Model Context Protocol (MCP) server for Kubernetes that allows LLM-powered applications to interact with Kubernetes clusters. It provides tools for listing and applying Kubernetes resources through the MCP protocol.
MKP is a Model Context Protocol (MCP) server for Kubernetes that allows
LLM-powered applications to interact with Kubernetes clusters. It provides tools
for listing and applying Kubernetes resources through the MCP protocol.

## Features

Expand All @@ -20,33 +22,39 @@ MKP is a Model Context Protocol (MCP) server for Kubernetes that allows LLM-powe

## Why MKP?

MKP offers several key advantages as a Model Context Protocol server for Kubernetes:
MKP offers several key advantages as a Model Context Protocol server for
Kubernetes:

### Native Go Implementation

- Built with the same language as Kubernetes itself
- Excellent performance characteristics for server applications
- Strong type safety and concurrency support
- Seamless integration with Kubernetes libraries

### Direct API Integration

- Uses Kubernetes API machinery directly without external dependencies
- No reliance on kubectl, helm, or other CLI tools
- Communicates directly with the Kubernetes API server
- Reduced overhead and improved reliability

### Universal Resource Support

- Works with any Kubernetes resource type through the unstructured client
- No hardcoded resource schemas or specialized handlers needed
- Automatically supports Custom Resource Definitions (CRDs)
- Future-proof for new Kubernetes resources

### Minimalist Design

- Focused on core Kubernetes resource operations
- Clean, maintainable codebase with clear separation of concerns
- Lightweight with minimal dependencies
- Easy to understand, extend, and contribute to

### Production-Ready Architecture

- Designed for reliability and performance in production environments
- Proper error handling and resource management
- Built-in rate limiting to protect against excessive API calls
Expand All @@ -63,22 +71,22 @@ MKP offers several key advantages as a Model Context Protocol server for Kuberne

1. Clone the repository:

```bash
git clone https://github.com/StacklokLabs/mkp.git
cd mkp
```
```bash
git clone https://github.com/StacklokLabs/mkp.git
cd mkp
```

2. Install dependencies:

```bash
task install
```
```bash
task install
```

3. Build the server:

```bash
task build
```
```bash
task build
```

## Usage

Expand All @@ -97,6 +105,7 @@ KUBECONFIG=/path/to/kubeconfig task run-with-kubeconfig
```

To run the server on a specific port:

```bash
MCP_PORT=9091 task run
```
Expand All @@ -110,6 +119,7 @@ The MKP server provides the following MCP tools:
Get a Kubernetes resource or its subresource.

Parameters:

- `resource_type` (required): Type of resource to get (clustered or namespaced)
- `group`: API group (e.g., apps, networking.k8s.io)
- `version` (required): API version (e.g., v1, v1beta1)
Expand Down Expand Up @@ -160,6 +170,7 @@ Example of getting logs from a specific container with parameters:
```

Available parameters for pod logs:

- `container`: Specify which container to get logs from
- `previous`: Get logs from previous container instance (true/false)
- `sinceSeconds`: Only return logs newer than a relative duration in seconds
Expand All @@ -168,16 +179,21 @@ Available parameters for pod logs:
- `limitBytes`: Maximum number of bytes to return
- `tailLines`: Number of lines to return from the end of the logs

By default, pod logs are limited to the last 100 lines and 32KB to avoid overwhelming the LLM's context window. These defaults can be overridden using the parameters above.
By default, pod logs are limited to the last 100 lines and 32KB to avoid
overwhelming the LLM's context window. These defaults can be overridden using
the parameters above.

Available parameters for regular resources:
- `resourceVersion`: When specified, shows the resource at that particular version

- `resourceVersion`: When specified, shows the resource at that particular
version

#### list_resources

Lists Kubernetes resources of a specific type.

Parameters:

- `resource_type` (required): Type of resource to list (clustered or namespaced)
- `group`: API group (e.g., apps, networking.k8s.io)
- `version` (required): API version (e.g., v1, v1beta1)
Expand All @@ -204,7 +220,9 @@ Example:
Applies (creates or updates) a Kubernetes resource.

Parameters:
- `resource_type` (required): Type of resource to apply (clustered or namespaced)

- `resource_type` (required): Type of resource to apply (clustered or
namespaced)
- `group`: API group (e.g., apps, networking.k8s.io)
- `version` (required): API version (e.g., v1, v1beta1)
- `resource` (required): Resource name (e.g., deployments, services)
Expand Down Expand Up @@ -264,10 +282,13 @@ Example:

#### post_resource

Posts to a Kubernetes resource or its subresource, particularly useful for executing commands in pods.
Posts to a Kubernetes resource or its subresource, particularly useful for
executing commands in pods.

Parameters:
- `resource_type` (required): Type of resource to post to (clustered or namespaced)

- `resource_type` (required): Type of resource to post to (clustered or
namespaced)
- `group`: API group (e.g., apps, networking.k8s.io)
- `version` (required): API version (e.g., v1, v1beta1)
- `resource` (required): Resource name (e.g., deployments, services)
Expand Down Expand Up @@ -300,11 +321,16 @@ Example of executing a command in a pod:
```

The `body` for pod exec supports the following fields:
- `command` (required): Command to execute, either as a string or an array of strings
- `container` (optional): Container name to execute the command in (defaults to the first container)
- `timeout` (optional): Timeout in seconds (defaults to 15 seconds, maximum 60 seconds)

- `command` (required): Command to execute, either as a string or an array of
strings
- `container` (optional): Container name to execute the command in (defaults to
the first container)
- `timeout` (optional): Timeout in seconds (defaults to 15 seconds, maximum 60
seconds)

Note on timeouts:

- Default timeout: 15 seconds if not specified
- Maximum timeout: 60 seconds (any larger value will be capped)
- Commands that exceed the timeout will be terminated and return a timeout error
Expand Down Expand Up @@ -332,16 +358,20 @@ The response includes stdout, stderr, and any error message:

### MCP Resources

The MKP server provides access to Kubernetes resources through MCP resources. The resource URIs follow these formats:
The MKP server provides access to Kubernetes resources through MCP resources.
The resource URIs follow these formats:

- Clustered resources: `k8s://clustered/{group}/{version}/{resource}/{name}`
- Namespaced resources: `k8s://namespaced/{namespace}/{group}/{version}/{resource}/{name}`
- Namespaced resources:
`k8s://namespaced/{namespace}/{group}/{version}/{resource}/{name}`

### Configuration

#### Controlling Resource Discovery

By default, MKP serves all Kubernetes resources as MCP resources, which provides useful context for LLMs. However, in large clusters with many resources, this can consume significant context space in the LLM.
By default, MKP serves all Kubernetes resources as MCP resources, which provides
useful context for LLMs. However, in large clusters with many resources, this
can consume significant context space in the LLM.

You can disable this behavior by using the `--serve-resources` flag:

Expand All @@ -353,11 +383,16 @@ You can disable this behavior by using the `--serve-resources` flag:
./build/mkp-server --kubeconfig=/path/to/kubeconfig --serve-resources=false
```

Even with resource discovery disabled, the MCP tools (`get_resource`, `list_resources`, `apply_resource`, `delete_resource`, and `post_resource`) remain fully functional, allowing you to interact with your Kubernetes cluster.
Even with resource discovery disabled, the MCP tools (`get_resource`,
`list_resources`, `apply_resource`, `delete_resource`, and `post_resource`)
remain fully functional, allowing you to interact with your Kubernetes cluster.

#### Enabling Write Operations

By default, MKP operates in read-only mode, meaning it does not allow write operations on the cluster, i.e. the `apply_resource`, `delete_resource`, and `post_resource` tools will not be available. You can enable write operations by using the `--read-write` flag:
By default, MKP operates in read-only mode, meaning it does not allow write
operations on the cluster, i.e. the `apply_resource`, `delete_resource`, and
`post_resource` tools will not be available. You can enable write operations by
using the `--read-write` flag:

```bash
# Run with write operations enabled
Expand All @@ -369,13 +404,18 @@ By default, MKP operates in read-only mode, meaning it does not allow write oper

### Rate Limiting

MKP includes a built-in rate limiting mechanism to protect the server from excessive API calls, which is particularly important when used with AI agents. The rate limiter uses a token bucket algorithm and applies different limits based on the operation type:
MKP includes a built-in rate limiting mechanism to protect the server from
excessive API calls, which is particularly important when used with AI agents.
The rate limiter uses a token bucket algorithm and applies different limits
based on the operation type:

- Read operations (list_resources, get_resource): 120 requests per minute
- Write operations (apply_resource, delete_resource): 30 requests per minute
- Default for other operations: 60 requests per minute

Rate limits are applied per client session, ensuring fair resource allocation across multiple clients. The rate limiting feature can be enabled or disabled via the command line flag:
Rate limits are applied per client session, ensuring fair resource allocation
across multiple clients. The rate limiting feature can be enabled or disabled
via the command line flag:

```bash
# Run with rate limiting enabled (default)
Expand Down Expand Up @@ -413,21 +453,26 @@ task deps

## Running as an MCP Server with ToolHive

MKP can be run as a Model Context Protocol (MCP) server using [ToolHive](https://github.com/stacklok/toolhive), which simplifies the deployment and management of MCP servers.
MKP can be run as a Model Context Protocol (MCP) server using
[ToolHive](https://github.com/stacklok/toolhive), which simplifies the
deployment and management of MCP servers.

### Prerequisites

1. Install ToolHive by following the [installation instructions](https://github.com/stacklok/toolhive#installation).
1. Install ToolHive by following the
[installation instructions](https://docs.stacklok.com/toolhive/guides-cli/install).
2. Ensure you have Docker or Podman installed on your system.
3. Configure your Kubernetes credentials (kubeconfig) for the cluster you want to interact with.
3. Configure your Kubernetes credentials (kubeconfig) for the cluster you want
to interact with.

### Running MKP with ToolHive (Recommended)

The easiest way to run MKP is using the packaged version available in ToolHive's registry:
The easiest way to run MKP is using the packaged version available in ToolHive's
registry:

```bash
# Enable auto-discovery to automatically configure supported clients
thv config auto-discovery true
# Register a supported client so ToolHive can auto-configure your environment
thv client setup

# Run the MKP server (packaged as 'k8s' in ToolHive)
# Mount your kubeconfig so the server can access your Kubernetes cluster
Expand All @@ -440,18 +485,21 @@ thv list
thv registry info k8s
```

This will mount your Kubernetes credentials and make the server available to your MCP-compatible clients.
This will mount your Kubernetes credentials and make the server available to
your MCP-compatible clients.

### Advanced Usage with Custom Configuration

For advanced users who need custom configuration, you can also run MKP using the container image directly:
For advanced users who need custom configuration, you can also run MKP using the
container image directly:

```bash
# Run the MKP server using the published container image
thv run --name mkp --transport sse --target-port 8080 --volume $HOME/.kube:/home/nonroot/.kube:ro ghcr.io/stackloklabs/mkp/server:latest
```

This command:

- Names the server instance "mkp"
- Uses the SSE transport protocol
- Mounts your local kubeconfig into the container (read-only)
Expand All @@ -471,7 +519,8 @@ To verify that the MKP server is running:
thv list
```

This will show all running MCP servers managed by ToolHive, including the MKP server.
This will show all running MCP servers managed by ToolHive, including the MKP
server.

To stop the MKP server:

Expand All @@ -493,17 +542,18 @@ thv rm k8s
thv rm mkp
```


## Contributing

We welcome contributions to this MCP server! If you'd like to contribute, please review
the [CONTRIBUTING guide](./CONTRIBUTING.md) for details on how to get started.
We welcome contributions to this MCP server! If you'd like to contribute, please
review the [CONTRIBUTING guide](./CONTRIBUTING.md) for details on how to get
started.

If you run into a bug or have a feature request, please
[open an issue](https://github.com/StacklokLabs/mkp/issues) in the
repository or join us in the `#mcp-servers` channel on our
[open an issue](https://github.com/StacklokLabs/mkp/issues) in the repository or
join us in the `#mcp-servers` channel on our
[community Discord server](https://discord.gg/stacklok).

## License

This project is licensed under the Apache v2 License - see the LICENSE file for details.
This project is licensed under the Apache v2 License - see the LICENSE file for
details.