AWS Labs EKS Model Context Protocol (MCP) Server

0.1.27 · active · verified Fri Apr 17

The `awslabs-eks-mcp-server` package provides a Python-based server implementation for the Model Context Protocol (MCP), designed specifically for AWS EKS environments. It enables machine learning models to be served and managed efficiently within Kubernetes. As an AWS Labs 'sample' project, it demonstrates best practices and patterns but may not carry the same long-term support or stability guarantees as official AWS SDKs. The current version is `0.1.27`, with a release cadence that reflects ongoing development in a pre-1.0 state.

Common errors

```
ModuleNotFoundError: No module named 'mcp_server'
```
cause The `awslabs-eks-mcp-server` package is not installed or the Python environment is incorrect.

fix Ensure the package is installed in the active environment: `pip install awslabs-eks-mcp-server`. If using a virtual environment, ensure it's activated.
```
TypeError: 'FastAPI' object is not callable
```
cause Attempting to run `uvicorn.run()` directly with the `FastAPI` instance returned by `app.get_app()` without correctly passing it to `uvicorn.run` or calling a `run()` method on the server object (which isn't always available).

fix Use `uvicorn.run(app.get_app(), host="0.0.0.0", port=8000)` where `app` is an instance of `ModelContextProtocolServer`. Ensure `uvicorn` is installed.
```
Failed to build wheel for grpcio
```
cause Installing `grpcio` or `grpcio-tools` (a dependency of `awslabs-eks-mcp-server`) can fail on some systems if required build tools (like C++ compilers) are missing.

fix Ensure you have the necessary build tools installed for your operating system (e.g., `build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS, Visual C++ Build Tools on Windows). Consider installing `grpcio` and `grpcio-tools` first: `pip install grpcio grpcio-tools` to debug build issues separately.

Warnings

gotcha This library is part of `aws-samples` and might not have the same level of official support, stability, or long-term maintenance guarantees as core AWS SDKs or services. It's intended as a reference implementation.
Fix: Be aware that breaking changes might occur more frequently, and community support might be limited. Consider forks or alternative solutions for production critical workloads requiring enterprise-level support.
gotcha The `awslabs-eks-mcp-server` package provides the server logic but requires `uvicorn` (or another ASGI server) to actually run the FastAPI application it exposes. `uvicorn` is not installed as a direct dependency.
Fix: Ensure `uvicorn` is installed separately using `pip install uvicorn[standard]` or `pip install uvicorn` alongside the main library.
breaking As a pre-1.0 version (0.1.x), the API surface of `awslabs-eks-mcp-server` is subject to breaking changes without adhering to strict semantic versioning. Methods, class names, or expected inputs may change between minor versions.
Fix: Always pin to specific patch versions (e.g., `awslabs-eks-mcp-server==0.1.27`) in `requirements.txt` or `pyproject.toml` and thoroughly test when upgrading to newer versions. Refer to the GitHub repository's commit history for changes.

Install

pip install awslabs-eks-mcp-server Install core library
pip install uvicorn[standard] Install Uvicorn for running the server

Imports

ModelContextProtocolServer
```
from mcp_server.server import ModelContextProtocolServer
```
This is the main class for instantiating and running an MCP server.
ModelProvider
```
from mcp_server.provider import ModelProvider
```
Abstract base class to be implemented by users providing models.

Quickstart

This quickstart demonstrates how to create a basic MCP server. It involves defining a custom `ModelProvider` class that implements the necessary methods to serve model artifacts and context. The `ModelContextProtocolServer` wraps this provider, exposing a FastAPI application. The server is then run using `uvicorn`, typically accessible via `http://localhost:8000` (or the configured port). Remember to install `uvicorn` separately.

import uvicorn
from mcp_server.server import ModelContextProtocolServer
from mcp_server.provider import ModelProvider

class MyModelProvider(ModelProvider):
    def __init__(self):
        super().__init__('my-model-provider-id')

    async def get_model_artifact_uri(self, model_id: str) -> str:
        # In a real scenario, this would return an S3 URI or similar
        print(f"Request for model_id: {model_id}")
        return f"s3://my-bucket/models/{model_id}/artifact.tar.gz"

    async def get_model_context(self, model_id: str) -> dict:
        # Return context specific to the model, e.g., framework, version
        return {"framework": "pytorch", "version": "1.13.1", "device": "cuda"}

# Instantiate your model provider
provider = MyModelProvider()

# Create the MCP server instance
app = ModelContextProtocolServer(provider=provider, port=8000)

# Run the FastAPI app using Uvicorn
# In a real deployment, you'd use a proper process manager (e.g., systemd, Kubernetes deployment)
# For local testing, you can run this file directly and access http://localhost:8000/docs

# Example of running the app via uvicorn programmatically
if __name__ == "__main__":
    print("Starting MCP server on http://localhost:8000")
    # Use reload=True for development, remove in production
    uvicorn.run(app.get_app(), host="0.0.0.0", port=8000)

view raw JSON →