# Quick Start Guide
Get up and running with MCP Presidio in under 5 minutes!
## Prerequisites
**For Python Installation:**
- Python 3.10 or higher
- pip package manager
**For Docker Installation:**
- Docker 20.10 or higher
- Docker Compose (optional)
## Installation Steps
### Option 1: Docker (Fastest & Easiest)
Perfect for getting started quickly without worrying about Python dependencies:
```bash
git clone https://github.com/cmalpass/mcp-presidio.git
cd mcp-presidio
docker build -t mcp-presidio:latest .
```
**Note:** See [DOCKER.md](DOCKER.md) for detailed Docker deployment instructions.
### Option 2: Quick Install with Python (Recommended)
Use the interactive installation script:
**Unix/Linux/macOS:**
```bash
git clone https://github.com/cmalpass/mcp-presidio.git
cd mcp-presidio
./install.sh
```
**Windows:**
```cmd
git clone https://github.com/cmalpass/mcp-presidio.git
cd mcp-presidio
install.bat
```
The script will guide you through:
- Installing dependencies
- Selecting language models (English required, others optional)
- Optional development tools
- Verification and testing
### Option 3: Manual Python Install
```bash
git clone https://github.com/cmalpass/mcp-presidio.git
cd mcp-presidio
pip install -e .
python -m spacy download en_core_web_lg
```
## Usage
### Option 1: Use with Claude Desktop (Docker)
1. Open your Claude Desktop config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
2. Add the MCP Presidio server with Docker:
```json
{
"mcpServers": {
"presidio": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"mcp-presidio:latest"
],
"env": {}
}
}
}
```
3. Restart Claude Desktop
### Option 2: Use with Claude Desktop (Python)
1. Open your Claude Desktop config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
2. Add the MCP Presidio server:
```json
{
"mcpServers": {
"presidio": {
"command": "python",
"args": ["-m", "mcp_presidio.server"],
"env": {}
}
}
}
```
3. Restart Claude Desktop
4. Start using PII detection in conversations:
```
Can you check this for PII: "My name is John Smith, email: john@example.com"
```
### Option 3: Run Docker Container Directly
Start the container:
```bash
docker run -i mcp-presidio:latest
```
Or with docker-compose:
```bash
docker-compose up -d
```
### Option 4: Run Python Directly
Start the server:
```bash
mcp-presidio
```
Or:
```bash
python -m mcp_presidio.server
```
The server will listen on stdio for MCP protocol messages.
## Quick Test
Test basic functionality:
```bash
python << 'EOF'
from mcp_presidio.server import analyze_text
import json
text = "Contact Jane at jane@example.com or 555-1234"
result = analyze_text(text)
print(json.dumps(json.loads(result), indent=2))
EOF
```
Expected output:
```json
[
{
"entity_type": "EMAIL_ADDRESS",
"start": 16,
"end": 33,
"score": 1.0,
"text": "jane@example.com"
},
{
"entity_type": "PHONE_NUMBER",
"start": 37,
"end": 45,
"score": 0.4,
"text": "555-1234"
}
]
```
## Example Use Cases
### 1. Detect PII in Customer Feedback
```
User: Can you analyze this customer review for PII?
"Great service! Email me at sarah@company.com if you have questions. - Sarah Johnson"
Claude: [Uses analyze_text tool]
Found 2 PII entities:
- PERSON: "Sarah Johnson"
- EMAIL_ADDRESS: "sarah@company.com"
```
### 2. Anonymize Before Sharing
```
User: Anonymize this before I share it with the team:
"John Smith (john@example.com) called from 555-0100 about his account"
Claude: [Uses anonymize_text tool]
Anonymized: "<PERSON> (<EMAIL_ADDRESS>) called from <PHONE_NUMBER> about his account"
```
### 3. Check JSON Data
```
User: Does this API response contain any PII?
{"user": "alice@test.com", "id": 12345, "ip": "192.168.1.1"}
Claude: [Uses analyze_structured_data tool]
Found PII in 2 fields:
- .user: EMAIL_ADDRESS
- .ip: IP_ADDRESS
```
### 4. Validate Custom Data
```
User: I need to detect employee IDs like EMP-123456
Claude: [Uses add_custom_recognizer tool]
Added custom recognizer for EMPLOYEE_ID pattern.
Now analyzing: "Employee Sarah (EMP-123456) submitted report"
Found: EMPLOYEE_ID: "EMP-123456"
```
## Available Tools
The server provides 10 tools:
1. **analyze_text** - Detect PII in text
2. **anonymize_text** - Anonymize PII with various methods
3. **get_supported_entities** - List all PII types
4. **add_custom_recognizer** - Add custom patterns
5. **batch_analyze** - Process multiple texts
6. **batch_anonymize** - Anonymize multiple texts
7. **get_anonymization_operators** - List anonymization methods
8. **analyze_structured_data** - Detect PII in JSON
9. **anonymize_structured_data** - Anonymize JSON data
10. **validate_detection** - Test detection accuracy
## Troubleshooting
### Docker Issues
- **Build fails:** Check Docker version: `docker --version` (must be 20.10+)
- **Container exits:** Ensure you're using `-i` flag: `docker run -i mcp-presidio:latest`
- **Out of memory:** Increase memory: `docker run -i --memory="2g" mcp-presidio:latest`
- **SSL errors:** These are environment-specific and won't affect production use
### Server won't start
- Check Python version: `python --version` (must be 3.10+)
- Verify installation: `pip show mcp-presidio`
- Check spaCy model: `python -m spacy validate`
### PII not detected
- Ensure spaCy model is downloaded: `python -m spacy download en_core_web_lg`
- Check if entity type is supported: Use `get_supported_entities` tool
- Adjust score threshold if needed
### Performance issues
- First request is slower (model loading)
- Subsequent requests are much faster (cached)
- Use batch operations for multiple documents
## Next Steps
- Read [DOCKER.md](DOCKER.md) for comprehensive Docker deployment guide
- Read [EXAMPLES.md](EXAMPLES.md) for detailed usage examples
- See [README.md](README.md) for complete documentation
- Check [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) for technical details
## Support
For issues or questions:
- GitHub Issues: https://github.com/cmalpass/mcp-presidio/issues
- Documentation: See README.md and EXAMPLES.md
## License
MIT License - see [LICENSE](LICENSE) file
