Docker MCP Toolkit Exploration

This project demonstrates how to set up and use a Docker MCP (Model Context Protocol) server to enable AI-assisted Docker operations in Cursor.

What is MCP?

MCP (Model Context Protocol) is a protocol that allows AI assistants to connect to external data sources, tools, and services. This enables AI to perform real-time operations and access contextual information.

Features

This Docker MCP server provides the following tools:

Container Management

• List Containers: View all Docker containers (running and stopped)
• Start Container: Start a stopped container by name or ID
• Stop Container: Stop a running container by name or ID
• Remove Container: Remove a container (with optional force flag)

Image Management

• List Images: View all Docker images on the system

System Information

• Docker Info: Get detailed Docker system information

Setup Instructions

Prerequisites

• Node.js (version 14 or higher)
• Docker Desktop or Docker Engine
• Cursor IDE

Installation

1. Clone or create this project

   # If starting fresh
   mkdir mcp-docker-exploration
   cd mcp-docker-exploration
   

2. Install dependencies

   npm install
   

3. Test the MCP server

   node docker-mcp-server.js
   

Cursor Integration

To integrate with Cursor, you need to configure the MCP server in your Cursor settings:

1. Open Cursor Settings

   • Go to Settings (Ctrl/Cmd + ,)
   • Search for "MCP" or "Model Context Protocol"

2. Add MCP Server Configuration

   • Add the path to your docker-mcp-server.js file
   • Or use the provided cursor-mcp-config.json as a reference

3. Restart Cursor

   • Restart Cursor to load the new MCP configuration

Usage Examples

Once configured, you can ask the AI assistant to:

• "Show me all Docker containers"
• "Start the container named 'my-app'"
• "Stop the container with ID 'abc123'"
• "Remove the stopped container 'old-container'"
• "List all Docker images"
• "Get Docker system information"

Available Tools

list_containers

Lists all Docker containers with options to show stopped containers.

Parameters:

• all (boolean, optional): Show all containers including stopped ones (default: true)

list_images

Lists all Docker images on the system.

start_container

Starts a stopped Docker container.

Parameters:

• container (string, required): Container name or ID to start

stop_container

Stops a running Docker container.

Parameters:

• container (string, required): Container name or ID to stop

remove_container

Removes a Docker container.

Parameters:

• container (string, required): Container name or ID to remove
• force (boolean, optional): Force removal of running container (default: false)

docker_info

Gets detailed Docker system information.

Development

Adding New Tools

To add new Docker operations, modify the docker-mcp-server.js file:

1. Add a new case in the tools/call handler
2. Implement the corresponding method
3. Add the tool definition to the tools/list handler

Testing

Test the server manually:

node docker-mcp-server.js

The server communicates via stdio, so you can test it by sending JSON messages to stdin.

Troubleshooting

Common Issues

1. Docker not found

   • Ensure Docker is installed and running
   • Check that docker command is available in PATH

2. Node.js not found

   • Install Node.js from https://nodejs.org/
   • Verify installation with node --version

3. MCP server not connecting

   • Check Cursor MCP configuration
   • Ensure the server file path is correct
   • Restart Cursor after configuration changes

Debug Mode

To run the server in debug mode, add logging:

console.error("Debug: Processing request:", request);

Security Considerations

• The MCP server has access to Docker commands
• Ensure proper permissions and access controls
• Consider running in a restricted environment for production use

Next Steps

Potential enhancements:

• Add Docker Compose support
• Implement image building and pushing
• Add network and volume management
• Create a web interface for management
• Add support for Docker Swarm

Resources

• MCP Protocol Documentation
• Docker CLI Reference
• Cursor Documentation