MCP Docker Hub Server

A Model Context Protocol (MCP) server that provides access to Docker Hub functionality through Claude with secure database storage for credentials.

Setup

1. Install dependencies:

   npm install
   

2. Database Setup:

   • Create a MySQL/MariaDB database
   • Run the SQL commands in DATABASE_SETUP.md
   • See config.example for environment variables

3. Create environment variables: Create a .env file in the root directory with:

   # Database Configuration
   DB_HOST=localhost
   DB_USER=root
   DB_PASSWORD=your_password_here
   DB_NAME=docker_hub_db
   DB_PORT=3306
   
   # Encryption Key (32 characters recommended)
   ENCRYPTION_KEY=your-secret-encryption-key-32-chars-long
   

   To get your Docker Hub access token:

   • Go to https://hub.docker.com/settings/security
   • Create a new access token
   • Use the docker_save_credentials tool to store securely

4. Run the server:

   node src/index.js
   

Features

Docker Hub Operations

• docker_search_images: Search for Docker images on Docker Hub

  • Parameters:
    • username (required): Docker Hub username
    • query (required): Search term
    • limit (optional): Number of results (default: 5)
    • page (optional): Page number (default: 1)

• docker_get_image_details: Get details of a particular image

• docker_list_tags: List tags for a specific image

• docker_get_manifest: Get image manifest

• docker_analyze_layers: Analyze image layers

Credential Management

• docker_save_credentials: Save or update Docker Hub credentials securely
• docker_get_credentials: Get credential metadata (username, dates)
• docker_list_credentials: List all active credentials
• docker_delete_credentials: Delete credentials for a user
• docker_test_db_connection: Test database connectivity

Troubleshooting

EPIPE Error

If you encounter Error: write EPIPE, this usually means:

1. The MCP client (Claude) closed the connection unexpectedly
2. There's a communication issue between the client and server

Solutions:

1. Restart Claude
2. Check that your environment variables are set correctly
3. Ensure the server is running before opening Claude
4. Check the console output for any error messages

Common Issues

1. Database connection failed: Check database server and credentials in .env
2. Missing encryption key: Ensure ENCRYPTION_KEY is set in .env
3. Invalid credentials: Use docker_save_credentials to store valid credentials
4. Network issues: Check your internet connection and Docker Hub API status
5. Table not found: Run the SQL commands in DATABASE_SETUP.md

Development

The server is built using:

• Node.js
• MCP SDK (@modelcontextprotocol/sdk)
• Axios for HTTP requests
• MySQL2 for database connectivity
• CryptoJS for encryption
• Dotenv for environment variable management

Security

• All Docker Hub Personal Access Tokens (PATs) are encrypted using AES-256 encryption
• Credentials are stored securely in the database
• No sensitive data is exposed through the MCP tools
• Soft delete ensures data recovery capability

Logs

The server provides detailed logging for debugging:

• MCP Server errors
• Transport errors
• Docker Hub API errors
• Process signals and shutdown events