# Docker Deployment Guide for MCP Presidio
This guide provides comprehensive instructions for deploying and using MCP Presidio in Docker containers.
## Table of Contents
- [Quick Start](#quick-start)
- [Building the Image](#building-the-image)
- [Running the Container](#running-the-container)
- [Configuration with MCP Clients](#configuration-with-mcp-clients)
- [Multi-Language Support](#multi-language-support)
- [Production Deployment](#production-deployment)
- [Troubleshooting](#troubleshooting)
## Quick Start
### Using Docker CLI
```bash
# Clone the repository
git clone https://github.com/cmalpass/mcp-presidio.git
cd mcp-presidio
# Build the Docker image
docker build -t mcp-presidio:latest .
# Run the container
docker run -i mcp-presidio:latest
```
### Using Docker Compose
```bash
# Clone the repository
git clone https://github.com/cmalpass/mcp-presidio.git
cd mcp-presidio
# Start the service
docker-compose up -d
# View logs
docker-compose logs -f mcp-presidio
# Stop the service
docker-compose down
```
## Building the Image
### Standard Build
```bash
docker build -t mcp-presidio:latest .
```
### Build with Custom Tag
```bash
docker build -t mcp-presidio:v1.0 .
```
### Build with Build Arguments (if needed)
```bash
docker build --build-arg PYTHON_VERSION=3.11 -t mcp-presidio:latest .
```
### Multi-Architecture Build
For deploying on different architectures (e.g., ARM for Apple Silicon, AMD64 for servers):
```bash
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 -t mcp-presidio:latest .
```
## Running the Container
### Interactive Mode (stdio transport)
This is the standard mode for MCP servers:
```bash
docker run -i mcp-presidio:latest
```
### Background Mode (for testing)
```bash
docker run -d --name mcp-presidio-test mcp-presidio:latest tail -f /dev/null
docker exec -it mcp-presidio-test python -m mcp_presidio.server
```
### With Resource Limits
```bash
docker run -i \
--memory="2g" \
--cpus="2" \
mcp-presidio:latest
```
## Configuration with MCP Clients
### Claude Desktop Configuration
Add to your `claude_desktop_config.json`:
#### Standard Docker Configuration
```json
{
"mcpServers": {
"presidio": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"mcp-presidio:latest"
],
"env": {}
}
}
}
```
#### With Resource Limits
```json
{
"mcpServers": {
"presidio": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--memory=2g",
"--cpus=2",
"mcp-presidio:latest"
],
"env": {}
}
}
}
```
#### Using Pre-Built Image from Registry
```json
{
"mcpServers": {
"presidio": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/cmalpass/mcp-presidio:latest"
],
"env": {}
}
}
}
```
### Other MCP Clients
For other MCP clients that support Docker containers, use similar configuration with the Docker run command.
## Multi-Language Support
The default Docker image includes only the English language model to minimize size. To support additional languages, you can build a custom image.
### Building Multi-Language Image
1. Create a custom Dockerfile (e.g., `Dockerfile.multilang`):
```dockerfile
# Multi-stage build for MCP Presidio with multiple languages
FROM python:3.11-slim as builder
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends \
gcc \
g++ \
&& rm -rf /var/lib/apt/lists/*
COPY pyproject.toml ./
COPY src ./src
RUN pip install --no-cache-dir --upgrade pip && \
pip install --no-cache-dir -e .
# Download multiple language models
RUN python -m spacy download en_core_web_lg && \
python -m spacy download es_core_news_lg && \
python -m spacy download fr_core_news_lg && \
python -m spacy download de_core_news_lg && \
python -m spacy download it_core_news_lg && \
python -m spacy download pt_core_news_lg
FROM python:3.11-slim
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends \
libgomp1 \
&& rm -rf /var/lib/apt/lists/*
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin
COPY --from=builder /app /app
COPY docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh
RUN useradd -m -u 1000 mcpuser && \
chown -R mcpuser:mcpuser /app
USER mcpuser
ENV PYTHONUNBUFFERED=1
ENV PYTHONDONTWRITEBYTECODE=1
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD python -c "import mcp_presidio.server; print('OK')" || exit 1
EXPOSE 8080
ENTRYPOINT ["docker-entrypoint.sh"]
```
2. Build the multi-language image:
```bash
docker build -f Dockerfile.multilang -t mcp-presidio:multilang .
```
**Note:** The multi-language image will be significantly larger (~2-3GB).
## Production Deployment
### Best Practices
1. **Use specific version tags instead of `latest`:**
```bash
docker build -t mcp-presidio:1.0.0 .
```
2. **Set resource limits:**
```yaml
# docker-compose.yml
deploy:
resources:
limits:
cpus: '2'
memory: 2G
reservations:
cpus: '1'
memory: 1G
```
3. **Use health checks:**
```yaml
healthcheck:
test: ["CMD", "python", "-c", "import mcp_presidio.server; print('OK')"]
interval: 30s
timeout: 3s
retries: 3
```
4. **Enable restart policies:**
```yaml
restart: unless-stopped
```
5. **Use read-only filesystem when possible:**
```bash
docker run -i --read-only --tmpfs /tmp mcp-presidio:latest
```
### Kubernetes Deployment
Example Kubernetes deployment:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: mcp-presidio
spec:
replicas: 2
selector:
matchLabels:
app: mcp-presidio
template:
metadata:
labels:
app: mcp-presidio
spec:
containers:
- name: mcp-presidio
image: mcp-presidio:latest
resources:
requests:
memory: "1Gi"
cpu: "500m"
limits:
memory: "2Gi"
cpu: "2"
stdin: true
tty: true
livenessProbe:
exec:
command:
- python
- -c
- "import mcp_presidio.server; print('OK')"
initialDelaySeconds: 5
periodSeconds: 30
```
## Troubleshooting
### Container Exits Immediately
**Problem:** Container exits right after starting.
**Solution:** The MCP server uses stdio transport and expects to communicate via stdin/stdout. Ensure you're running with `-i` flag:
```bash
docker run -i mcp-presidio:latest
```
### Out of Memory Errors
**Problem:** Container crashes with OOM (Out of Memory) errors.
**Solution:** Increase memory limit:
```bash
docker run -i --memory="4g" mcp-presidio:latest
```
### Language Model Not Found
**Problem:** Error about missing language model when using non-English languages.
**Solution:** Build a custom image with the required language models. See [Multi-Language Support](#multi-language-support).
### Permission Denied Errors
**Problem:** Permission errors when accessing files.
**Solution:** The container runs as non-root user (mcpuser). Ensure mounted volumes have correct permissions:
```bash
chown -R 1000:1000 /path/to/mounted/directory
```
### Slow Performance
**Problem:** Slow PII detection performance.
**Solution:**
1. Increase CPU allocation: `--cpus="4"`
2. Ensure language models are properly loaded
3. Check if running on correct architecture (use native builds)
### Debug Mode
To debug issues, run the container interactively with a shell:
```bash
docker run -it mcp-presidio:latest bash
```
Then test the server manually:
```bash
python -m mcp_presidio.server
```
### View Container Logs
```bash
# For running container
docker logs mcp-presidio
# For docker-compose
docker-compose logs -f mcp-presidio
```
### Inspect Container
```bash
# View container details
docker inspect mcp-presidio
# Check resource usage
docker stats mcp-presidio
```
## Security Considerations
1. **⚠️ PRIVACY WARNING:** Using this container via an LLM agent implies sharing PII with the LLM provider. PII in prompts is sent to the LLM *before* this tool can detect/anonymize it.
2. **Non-Root User:** The container runs as a non-root user (UID 1000) for security.
3. **Minimal Base Image:** Uses Python slim image to reduce attack surface.
3. **Read-Only Filesystem:** Consider running with read-only filesystem:
```bash
docker run -i --read-only --tmpfs /tmp mcp-presidio:latest
```
4. **Network Isolation:** The container doesn't require network access for core functionality (all processing is local).
5. **No Sensitive Data in Image:** The image doesn't contain any credentials or sensitive data.
6. **Regular Updates:** Keep the base image and dependencies updated:
```bash
docker build --no-cache -t mcp-presidio:latest .
```
## Image Size Optimization
Current image sizes:
- **Base image (English only):** ~500MB
- **Multi-language image:** ~2-3GB
To further optimize:
1. **Use Alpine base (advanced):**
```dockerfile
FROM python:3.11-alpine
```
Note: Alpine requires additional compilation for some dependencies.
2. **Selective language models:** Include only the languages you need.
3. **Layer caching:** Order Dockerfile commands from least to most frequently changing.
## Support
For issues specific to Docker deployment:
1. Check this guide's [Troubleshooting](#troubleshooting) section
2. Review Docker logs: `docker logs <container_name>`
3. Open an issue on [GitHub](https://github.com/cmalpass/mcp-presidio/issues)
For general MCP Presidio issues, see the main [README.md](README.md).
