Provides containerized deployment of the MCP server with volume mounting for persistent storage of API keys, simplifying setup and operation across different environments.
Offers integration with Python applications through the fastmcp client library, enabling programmatic access to MCP tools and capabilities from Python code.
🐳 MCP Dockerized
A containerized Model Context Protocol (MCP) server that can be easily deployed via Docker with extensible tools and secure API key authentication.
Features
- ✅ Containerized Deployment: Easy deployment via Docker Compose
- ✅ Configurable Port: Listen on any port via environment variables
- ✅ Health Check Endpoint: Built-in health monitoring
- ✅ API Key Authentication: Secure access with unlimited API keys
- ✅ Timestamped Logging: Configurable log levels with timestamps
- ✅ Extensible Tools: Abstract tool system for easy extension
- ✅ Console Tool: Execute host machine commands
- ✅ MCP Protocol Compliance: Follows Model Context Protocol specification
- ✅ Tool Discovery: Automatic endpoint to describe all available tools
Quick Start
- Clone and setup:
- Configure environment (optional):
- Start the server:
- Get your API key:
Configuration
Environment Variables
Variable | Default | Description |
---|---|---|
MCPD_PORT | 8000 | Port for the MCP server |
MCPD_LOG_LEVEL | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) |
MCPD_API_KEY_LENGTH | 32 | Length of generated API keys |
Example .env
file:
API Endpoints
Health Check
Authentication
All API endpoints require a Bearer token in the Authorization header:
Core Endpoints
List Tools
Returns descriptions of all available tools.
Execute Tool
Generate New API Key
MCP Protocol Endpoints
Initialize MCP Connection
List MCP Tools
Call MCP Tool
Available Tools
Console Tool
Execute commands on the host machine.
Parameters:
command
(required): The command to executetimeout
(optional): Timeout in seconds (default: 30)working_directory
(optional): Working directory for execution
Example:
API Key Management
Initial API Key
The server generates an initial API key on first startup. Check the logs:
Generate Additional API Keys
Using the API
Creating Custom Tools
1. Create a New Tool File
Create a new file in the mcp_tools/
directory following the naming pattern *_tool.py
:
2. Register the Tool
Add your tool to the load_tools()
method in main.py
:
3. Rebuild and Deploy
Development
VS Code Extensions for Testing
For the best development experience, install these VS Code extensions:
Primary Testing Extension
- REST Client (
humao.rest-client
) - Test API endpoints directly in VS Code
Development Extensions
- Python (
ms-python.python
) - Python language support - Python Debugger (
ms-python.debugpy
) - Advanced Python debugging - Docker (
ms-azuretools.vscode-docker
) - Docker container management - YAML (
redhat.vscode-yaml
) - YAML file validation
Alternative HTTP Clients
- Thunder Client (
rangav.vscode-thunder-client
) - Postman-like interface - Postman (
postman.postman-for-vscode
) - Official Postman extension
Testing with REST Client
- Get your API key:
- Use your preferred HTTP client to test the API endpoints
- Use VS Code tasks (Ctrl+Shift+P → "Tasks: Run Task"):
- Start MCP Server
- Stop MCP Server
- Test MCP Server
- Generate API Key
- View Server Logs
Local Development Setup
- Install dependencies:
- Run locally:
Testing
Test the health endpoint:
Test tool listing:
Test console tool:
Security Considerations
- API Keys: Store API keys securely and rotate them regularly
- Console Tool: The console tool can execute any command - use with caution
- Network: Consider running behind a reverse proxy in production
- Container Security: Run as non-root user (already configured)
Monitoring and Logs
View Logs
Health Monitoring
The server includes a health check endpoint that's automatically used by Docker Compose:
Troubleshooting
Server Won't Start
- Check port availability:
- Check logs:
API Key Issues
- Generate new API key using the API:
- Check existing keys:
Tool Execution Fails
- Check tool parameters schema
- Verify authentication
- Check server logs for detailed error messages
License
MIT License - see LICENSE file for details.
Contributing
- Fork the repository
- Create a feature branch
- Add your changes
- Add tests if applicable
- Submit a pull request
Support
For issues and questions, please open an issue on the GitHub repository.
Docker Hub Deployment
Pre-built Images
MCP Dockerized is available on Docker Hub with support for multiple Linux platforms:
- Linux AMD64/ARM64/ARM v7:
antpavlenkohmcorp/mcp-dockerized:latest
Quick Start with Docker Hub
Linux/macOS:
Windows:
Using Docker Compose with Docker Hub:
Platform-Specific Pulls
Building and Publishing Your Own Images
Prerequisites:
- Docker Desktop with buildx support
- Docker Hub account
Manual Build Process:
Automated Builds with GitHub Actions:
The repository includes GitHub Actions workflows for automated building and testing.
For Pull Requests: The workflow will build and test Docker images without requiring any setup.
For Publishing to Docker Hub: If you want to automatically publish images to Docker Hub, set these secrets in your GitHub repository settings (Settings → Secrets and variables → Actions):
DOCKER_USERNAME
: Your Docker Hub usernameDOCKER_PASSWORD
: Your Docker Hub password or access token
Note: Without these secrets, the workflow will still build and test the images for pull requests, but won't publish them to Docker Hub.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A minimal, containerized MCP server that exposes a Streamable HTTP transport with API key authentication, allowing secure access to MCP endpoints.
Related MCP Servers
- -securityAlicense-qualityAn MCP server that exposes HTTP methods defined in an OpenAPI specification as tools, enabling interaction with APIs via the Model Context Protocol.Last updated -8PythonMIT License
mcp-confluentofficial
AsecurityAlicenseAqualityAn MCP server implementation built to interact with Confluent Kafka and Confluent Cloud REST APIs.Last updated -242485TypeScriptMIT License- -securityAlicense-qualityA reference implementation for creating an MCP server supporting Streamable HTTP & SSE Transports with OAuth authorization, allowing developers to build OAuth-authorized MCP servers with minimal configuration.Last updated -71TypeScriptMIT License
- -securityAlicense-qualityA server that implements the Model Context Protocol (MCP) with StreamableHTTP transport, enabling standardized interaction with model services through a RESTful API interface.Last updated -1331JavaScriptMIT License