Creating a Docker MCP server in Python

Introduction

For the past week or so I have been encountering Model Context Protocol (MCP) being mentioned here and there, so I decided to dive in and experiment with it to get a better understanding. In just a day, I got an MCP server up and running in Python, letting me build and run a container image using nothing but natural language — and I’ve got to say, the hype is real. It’s pretty cool 😎.

Model Context Protocol (MCP)

For those unfamiliar with MCP, here’s my best attempt at a simple explanation. Also, I’m not an AI expert, so if you want a deeper understanding, I highly recommend checking out the official site modelcontextprotocol.io.

MCP is a framework that allows Large Language Models (LLMs) to interact with external tools and services through well-defined interfaces. A key part of this framework is the MCP server, which is what I’ve roughly built using Python and the FastMCP package.

This server exposes Docker container and image management capabilities through a well-defined API that LLMs can understand and use. It essentially acts as a bridge between natural language requests and the Docker engine.

Unlike traditional APIs, where clients need to know specific endpoints and data formats, MCP is designed for LLMs to dynamically understand and use available functions based on provided schemas.

Now, let’s dive deeper into what this looks like in code, as well as throughout this blog post.

Python Code for MCP server

So alongside not being an AI expert, I’m also not a Python expert, so keep that in mind as I share the code with you. My goal here was simply to get a better understanding of how MCP servers work and to get a basic implementation going.

Also worth noting, there exists a community offering of a Docker MCP server that is miles ahead of what I’ve built. You can find it here.

To expand on my goal, I simply wanted to get a basic implementation going that allows me to build and run a container image using nothing but natural language - and I think I’ve succeeded at that.

Using the FastMCP package, I was able to build a basic MCP server thanks to the @mcp.tool() decorator that’s provided. This decorator is responsible for generating the schemas I mentioned earlier and making the functions available to the LLM.

These schemas are automatically created based on:

Function signatures (parameters, return types)
Docstrings (if present, they help provide descriptions)
Returned values (MCP expects structured responses that align with the defined return type)

To see what this looks like in action, you can find the code below.

import docker
from mcp.server.fastmcp import FastMCP

# Initialize FastMCP server
mcp = FastMCP("docker")

# Initialize Docker client
docker_client = docker.from_env()


def format_container_list_output(container) -> str:
    """Format Docker container list into a readable string."""
    return f"""
Name: {container.name}
ID: {container.short_id}
Status: {container.status}
Image: {container.image.tags[0] if container.image.tags else container.image.id[:12]}
Created: {container.attrs.get('Created', 'Unknown')}
Started: {container.attrs.get('State', {}).get('StartedAt', 'Unknown')}
Ports: {container.ports}
Errors: {container.attrs.get('State', {}).get('Error', 'Unknown')}
"""


def format_container_logs_output(logs) -> str:
    """Format Docker container logs into a readable string."""
    return logs.decode("utf-8")


@mcp.tool()
async def list_containers(all: bool = False) -> str:
    """List Docker containers.

    Args:
        all: If True, show all containers (including stopped ones). Default is False (only running).
    """
    containers = [
        container
        for container in docker_client.containers.list(all=all)
        if "my" in container.name
    ]

    if not containers:
        return f"No {'containers' if all else 'running containers'} found."

    # Add a header to clarify what we're showing
    header = f"Showing {'all' if all else 'only running'} containers:"
    result = [header, "-" * len(header)]

    for container in containers:
        result.append(format_container_list_output(container))
    return "\n".join(result)


@mcp.tool()
async def get_container_logs(container_id: str, container_name: str) -> str:
    """Get logs for a specific container.

    Args:
        container_id: The ID of the container to get logs for.
    """

    logs = docker_client.containers.get(container_id).logs(tail=20)

    return f"""
    Container Name: {container_name}
    Logs:
        {format_container_logs_output(logs)}
    """


@mcp.tool()
async def build_image(dockerfile_path: str, tag: str = None) -> str:
    """Build a Docker image from a Dockerfile.

    Args:
        dockerfile_path: Absolute path to the Dockerfile (e.g., '/path/to/project/Dockerfile')
        tag: Tag to assign to the built image (e.g., 'myapp:latest')
    """
    import os

    # Set context_path to the directory containing the Dockerfile
    context_path = os.path.dirname(os.path.abspath(dockerfile_path))

    try:
        image, build_logs = docker_client.images.build(
            path=context_path,
            dockerfile=os.path.basename(dockerfile_path),
            tag=tag,
            rm=True,
        )

        return f"""
        Status: Success
        Tag: {tag}
        Image ID: {image.id}
        """

    except Exception as e:
        return f"""
        Status: Failed
        Error: {str(e)}
        """


@mcp.tool()
async def run_container(image_id: str, container_name: str, ports: dict = None) -> str:
    """Run a Docker container from an image.

    Args:
        image_id: The ID of the image to run.
        container_name: The name of the container to run.
        ports: A dictionary of ports to expose on the container.
    """
    if ports is None:
        ports = {"8080": 80}

    try:
        container = docker_client.containers.run(
            image_id, ports=ports, detach=True, name=container_name
        )

        return f"""
        Status: Success
        Container Name: {container.name}
        Container ID: {container.id}
        Ports: {container.ports}
        """

    except Exception as e:
        return f"""
        Status: Failed
        Container Name: {container_name}
        Error: {str(e)}
        """


@mcp.tool()
async def remove_container(container_name: str) -> str: 
    """Remove a Docker container.

    Args:
        container_name: The name of the container to remove.
    """
    try:
        container = docker_client.containers.get(container_name)
        container.remove(force=True)

        return f"""
        Status: Success
        Container Name: {container_name}
        """
    
    except Exception as e:
        return f"""
        Status: Failed
        Container Name: {container_name}
        """

if __name__ == "__main__":
    mcp.run(transport="stdio")

Setting the Stage

Before diving into my interaction with the LLM, let’s first set the stage a bit.

So I used Cursor to help with writing the code for the MCP server, and it’s also where I added the server to test things out. For those interested, I was using the claude-3.7-sonnet model from Anthropic.

It’s also worth noting that MCP isn’t limited to Cursor—there are other tools that support it as well.

To start, I created a simple Dockerfile in my project directory that I would be building and running.

FROM nginx:alpine

WORKDIR /usr/share/nginx/html

RUN rm -rf ./*

COPY index.html .

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

Then, the contents of my index.html file which is also very simple.

<!DOCTYPE html>
<html>
<head>
    <title>Welcome</title>
</head>
<body>
    <h1>Welcome to my test app!</h1>
    <p>This is a simple Nginx container.</p>
</body>
</html>

Finally, I added the MCP server to Cursor so that it would know to use it. Nothing exciting here, instructions can be found here.

Here’s what it looks like in Cursor.

Cursor MCP server

So, if you look at this alongside the Python code I shared earlier, you can see that each function is available for Cursor to use. This is the magic, so to speak, that allows the LLM to recognize what functions exist and how to use them to assist with your requests.

With all that in place, let’s dive into how this all works.

Building and Running a Container Image

So that now Cursor is aware of what functions exist, it will be smart enough to pick up on cues in our conversation and use them when needed.

Here’s a part of our conversation, whereby you can see that I’ve asked Cursor to build and run a container image of my application (notice the please - gotta be polite to AI 😉).

Build and Run Container

Doesn’t get any simpler than that folks.

So to summarize what happened here:

Cursor first quickly scanned my project directory to understand what files were present (this is more of a Cursor feature than MCP).
Cursor also knew that it had access to functions to build and run a container image.
Based on my request, it knew to use those commands to fullfil it.
After running the container, it knew it could list running containers to confirm it was actually running.
Finally, it was smart enough to know what port it would be available on for me to interact with.

So this is obviously a pretty simple example, but you can really start to see the potential of how powerful MCP can be.

I can easily add more functions to expand on what Cursor can do for me, such as a function called push_image that would push my built image to a container registry. I could even add a Kubernetes MCP server with a deploy_image function that would allow me to deploy my built image to a k8s cluster. All this done through simple natural language requests.

Wild stuff 🤯

Parameters Being Passed to the MCP server

I want to quickly explain how Cursor interacts with the MCP server and how the Python code is structured to generate the schemas that make it so effective.

Let’s first start with the inputs, or what operations are available to Cursor. These are primarily determined by the functions in my Python code, while the parameters help tweak how those operations actually run.

A good example to showcase this is the build_image function.

@mcp.tool()
async def build_image(dockerfile_path: str, tag: str = None) -> str:
    """Build a Docker image from a Dockerfile.

    Args:
        dockerfile_path: Absolute path to the Dockerfile (e.g., '/path/to/project/Dockerfile')
        tag: Tag to assign to the built image (e.g., 'myapp:latest')
    """

This function is expecting the bare minimum to build a Docker image:

dockerfile_path: The absolute path to the Dockerfile.
tag: The tag to assign to the built image.

An important detail here is the role docstrings play here. The docstring explicitly states that dockerfile_path must be an absolute path, and Cursor picks up on this when interacting with the MCP server. This helps guide the LLM to use parameters more effectively.

If you expand the box that shows the interaction between Cursor and the MCP server you’ll see it provides these parameters on its own.

{
  "dockerfile_path": "/home/stu/Code/local/my-test-app/Dockerfile",
  "tag": "my-test-app:latest"
}

This highlights three (3) key things:

Cursor can figure out what values to use on its own, allowing for a hands-off approach.
I can also provide my own values, and if Cursor can fit them into the right parameter, it will. For example, I could have just added "use the name my-app and tag v1.0.0" to my prompt, and Cursor would have handled it.
The more parameters I expose, the more flexibility I have in how my image is built. I could easily add a labels parameter that would specify what labels I want to be added to the image.

Now, let’s move over to the outputs— the responses or return values I’ve set up that provide valuable information to Cursor, helping it assist me more effectively.

A good example to showcase this is the list_containers function, which is actually using another function called format_container_list_output to format the output into readable text.

def format_container_list_output(container) -> str:
    """Format Docker container list into a readable string."""
    return f"""
Name: {container.name}
ID: {container.short_id}
Status: {container.status}
Image: {container.image.tags[0] if container.image.tags else container.image.id[:12]}
Created: {container.attrs.get('Created', 'Unknown')}
Started: {container.attrs.get('State', {}).get('StartedAt', 'Unknown')}
Ports: {container.ports}
Errors: {container.attrs.get('State', {}).get('Error', 'Unknown')}
"""

This should be structured as JSON, but for this example, I kept it simple.

If you remember during my conversation with Cursor it was able to confirm that the container was running, as well as what port it was available on. That was made possible due to the information I’ve decided to include in the output.

Here’s a glimpse into what that interaction looked like.

Cursor List Container Output

So similar highlights to mention here:

Cursor can determine on its own if a container is running based on the status value I return. Same thing for what port it’s running on, as I’m returning the ports value.
I can ask Cursor to "list all containers created in the last week", and since I’m providing a created value, it can handle that request.
The more output values I supply, the more helpful Cursor becomes.

The main takeaway: inputs define what Cursor can do, while output values determine how useful its responses will be.

I got one last example to really drive these points home.

Cursor Saves the Day

So in this interaction I’m going to go through the same set of instructions as before, however this time I’ve purposefully introduce a bug in my Dockerfile whereby I’ve added the instruction USER nginx without actually ensuring the permissions are set correctly.

Let’s see how Cursor reacts.

Cursor Saves the Day

So to recap what happened here:

Cursor used the list_containers function once again to confirm that the container was running.
It noticed it wasn’t actually running, so it re-ran the same function but this time set the all parameter to True to list all containers.
This time it saw the container it was looking for, but the status value was exited.
Because I’ve created a function called get_container_logs it knew to use that, and therefore was able to parse the logs on its own to determine the error.
Finally, it provided me with a way to resolve the issue (this is once again more of a Cursor feature than MCP).

Conclusion

Hopefully this simple overview shows the power and potential of MCP. I had a lot of fun playing around with this, and probably will tinker a bit more to get a workflow going that would utilize multiple MCP servers.

Also worth noting that there were a few interactions that I had with Cursor that I just couldn’t include in this blog post, but still found super cool. Notable ones are:

There was a time I went to go deploy my container image without removing it previously. Cursor was able to see it was already running so used the remove_container function to remove it before re-deploying.
There was a time when a port was already being used, so Cursor used the list_containers to confirm it was actually in use and then suggested a different port when deploying a container image.

Thanks for taking the time to read through this blog post. I hope you found it interesting and helpful!

👋

Introduction#

Model Context Protocol (MCP)#

Python Code for MCP server#

Setting the Stage#

Building and Running a Container Image#

Parameters Being Passed to the MCP server#

Cursor Saves the Day#

Conclusion#

Introduction

Model Context Protocol (MCP)

Python Code for MCP server

Setting the Stage

Building and Running a Container Image

Parameters Being Passed to the MCP server

Cursor Saves the Day

Conclusion