# MCP Document Server - Deployment Summary
**Built for**: Aaron Watson
**Purpose**: Local document access for Claude AI
**Date**: January 2026
## 📦 What You Got
A complete, production-ready MCP (Model Context Protocol) server that allows Claude to securely access your work documents.
### Package Contents
```
mcp-document-server/
├── server.py # Main MCP server implementation
├── requirements.txt # Python dependencies
├── Dockerfile # Container definition
├── docker-compose.yml # Docker orchestration
├── .env.example # Configuration template
├── .gitignore # Version control exclusions
├── install.sh # Automated setup script
├── test_server.py # Test suite
├── mcp-document-server.service # Systemd service file
├── README.md # Complete documentation
├── QUICKSTART.md # 5-minute setup guide
├── CLAUDE_INTEGRATION.md # Claude Desktop setup
└── OPNSENSE_INTEGRATION.md # Your network integration
```
## 🎯 Perfect for Your Setup
This server is specifically designed for your infrastructure:
✅ **OPNsense Integration**: Documented firewall rules and VLAN setup
✅ **Tailscale Ready**: Access from anywhere securely
✅ **Docker Native**: Fits your existing container ecosystem
✅ **Home Assistant Compatible**: Can add monitoring
✅ **Read-Only**: Your documents stay safe
## 🚀 Quick Deployment Path
### On Your Home Server
```bash
# 1. Copy to your server
scp -r mcp-document-server/ homeserver:/opt/
# 2. SSH to server
ssh homeserver
# 3. Run installer
cd /opt/mcp-document-server
chmod +x install.sh
sudo ./install.sh
# 4. Configure documents path
sudo nano docker-compose.yml
# Change: - ./documents:/documents:ro
# To: - /path/to/work/docs:/documents:ro
# 5. Start server
sudo docker-compose up -d
# 6. Enable systemd service (optional)
sudo systemctl enable mcp-document-server
sudo systemctl start mcp-document-server
```
### On Your Work Laptop
```bash
# 1. Edit Claude Desktop config
nano ~/.config/claude/claude_desktop_config.json
# 2. Add this:
{
"mcpServers": {
"work-documents": {
"command": "docker",
"args": ["exec", "-i", "mcp-document-server", "python", "server.py"],
"env": {"MCP_TRANSPORT": "stdio"}
}
}
}
# 3. Restart Claude Desktop
# 4. Test it!
# Ask Claude: "Can you list my work documents?"
```
## 🔧 Your Network Integration
### Tailscale Access
1. Server will be accessible at your Tailscale IP (e.g., `100.x.x.x:8000`)
2. No WAN port forwarding needed - fully secure
3. Works from anywhere with Tailscale connection
### OPNsense Firewall Rules
Add these rules (see OPNSENSE_INTEGRATION.md for details):
**Firewall > Rules > LAN**:
- Allow TCP from LAN net to Docker host (192.168.x.x) port 8000
**Firewall > Rules > Tailscale**:
- Allow TCP from Tailscale net to Docker host port 8000
### DNS (Optional)
Add Unbound override:
- Host: `mcp`
- Domain: `home.local`
- IP: Your Docker host IP
Access at: `http://mcp.home.local:8000`
## 📚 Available Tools for Claude
Once connected, Claude can:
### 1. List Documents
```
Claude, list all my work documents from 2024
```
### 2. Read Documents
```
Claude, read the Q4 strategic plan and summarize it
```
### 3. Search Documents
```
Claude, search my documents for "EPA action items"
```
### 4. Analyze Documents
```
Claude, compare the FY25 and FY26 work plans
```
## 🔒 Security Features
✅ **Read-Only**: Claude cannot modify your documents
✅ **Path Protection**: Cannot access files outside documents directory
✅ **Type Filtering**: Only allowed file extensions
✅ **Size Limits**: Configurable max file size
✅ **Tailscale Encryption**: All remote traffic encrypted
✅ **No WAN Exposure**: Not accessible from internet
## 📊 Supported File Types
- **Documents**: PDF, DOCX, PPTX
- **Spreadsheets**: XLSX, CSV
- **Text**: TXT, MD, JSON, YAML, LOG
- **More**: Easy to add support for other formats
## 🎨 Customization Options
### Different Document Directories
Run multiple instances for different document sets:
```bash
# Work documents
docker-compose -f docker-compose.work.yml up -d
# Personal documents
docker-compose -f docker-compose.personal.yml up -d
```
### Authentication
Add a token in `.env`:
```bash
MCP_AUTH_TOKEN=your-secret-token
```
### File Size Limits
Adjust in `.env`:
```bash
MAX_FILE_SIZE_MB=20 # Increase for larger files
```
## 🐛 Troubleshooting Quick Reference
### Server Won't Start
```bash
docker-compose logs -f
docker ps -a | grep mcp
```
### Can't Access from Tailscale
```bash
# On server
tailscale status
docker ps | grep mcp
# From laptop
ping <tailscale-ip>
curl http://<tailscale-ip>:8000/health
```
### Claude Can't Connect
```bash
# Check config syntax
cat ~/.config/claude/claude_desktop_config.json | jq .
# Test server
python test_server.py
# Check Claude Desktop logs
tail -f ~/.config/claude/logs/mcp.log
```
## 📈 Monitoring
### Docker Logs
```bash
docker-compose logs -f
```
### Systemd Logs
```bash
sudo journalctl -u mcp-document-server -f
```
### Health Check
```bash
curl http://localhost:8000/health
```
### Home Assistant Integration (Optional)
Add to `configuration.yaml`:
```yaml
sensor:
- platform: rest
name: MCP Server Status
resource: http://mcp.home.local:8000/health
```
## 🔄 Updates & Maintenance
### Update Server Code
```bash
cd /opt/mcp-document-server
git pull # If using git
sudo docker-compose up -d --build
```
### Restart Server
```bash
sudo docker-compose restart
# or
sudo systemctl restart mcp-document-server
```
### View Logs
```bash
sudo docker-compose logs --tail=100
```
## 💡 Pro Tips
1. **Organize Your Documents**: Create subdirectories for different projects
2. **Use Symbolic Links**: Link to existing document locations
3. **Set Up Backups**: Regular backups of important documents
4. **Monitor Logs**: Occasionally check for errors
5. **Keep It Updated**: Pull updates periodically
## 🎯 Next Steps
1. **Deploy to your home server** following Quick Deployment Path
2. **Configure OPNsense** firewall rules
3. **Test Tailscale access** from your laptop
4. **Connect Claude Desktop** and test document access
5. **Add your work documents** to the documents directory
## 📞 Support Resources
- **Main README**: Complete documentation
- **Quick Start**: 5-minute setup guide
- **Claude Integration**: Claude Desktop setup
- **OPNsense Guide**: Network integration details
- **Test Script**: `python test_server.py`
## 🏆 What Makes This Special
This isn't just a generic MCP server - it's **specifically designed for your environment**:
- Integrates with your OPNsense firewall
- Works with your Tailscale VPN
- Fits your Docker infrastructure
- Supports your document types
- Respects your security requirements
- Includes your preferred file formats
## ⚡ Performance
- **Fast**: Direct file access, no cloud intermediary
- **Efficient**: Caches nothing, reads on demand
- **Scalable**: Handle hundreds of documents
- **Lightweight**: ~512MB RAM, minimal CPU
## 🎉 You're All Set!
Everything you need is included. Follow the Quick Deployment Path above and you'll have Claude accessing your work documents in minutes.
**Questions?** Check the documentation files included in this package.
---
**Built with**: Python, MCP SDK, Docker, FastAPI
**Tested on**: Ubuntu 24, Docker 24+
**Compatible with**: Claude Desktop, Claude API
**License**: MIT (use freely!)
