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

Install dependencies:
```
npm install
```
Database Setup:
- Create a MySQL/MariaDB database
- Run the SQL commands in DATABASE_SETUP.md
- See config.example for environment variables
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
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:

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

Solutions:

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

Common Issues

Database connection failed: Check database server and credentials in .env
Missing encryption key: Ensure ENCRYPTION_KEY is set in .env
Invalid credentials: Use docker_save_credentials to store valid credentials
Network issues: Check your internet connection and Docker Hub API status
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

Setup

Install dependencies:

npm install

Database Setup:

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

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

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:

The MCP client (Claude) closed the connection unexpectedly

There's a communication issue between the client and server

Solutions:

Restart Claude

Check that your environment variables are set correctly

Ensure the server is running before opening Claude

Check the console output for any error messages

Common Issues

Database connection failed: Check database server and credentials in .env

Missing encryption key: Ensure ENCRYPTION_KEY is set in .env

Invalid credentials: Use docker_save_credentials to store valid credentials

Network issues: Check your internet connection and Docker Hub API status

Table not found: Run the SQL commands in DATABASE_SETUP.md