# MCP Document Server
A secure Model Context Protocol (MCP) server that provides Claude AI with access to your local documents. Built for Aaron's work document integration needs.
## Features
- 🔒 **Secure**: Read-only access with path traversal protection
- 📁 **File Support**: PDF, DOCX, XLSX, PPTX, TXT, MD, JSON, YAML, CSV, LOG
- 🔍 **Search**: Full-text search across documents
- 🐳 **Docker**: Easy deployment with Docker Compose
- 🌐 **Network**: Works over HTTP (SSE) or local STDIO
- 🔌 **Tailscale Ready**: Integrate with your existing Tailscale network
## Quick Start
### Option 1: Docker Compose (Recommended)
1. **Clone and setup**:
```bash
cd mcp-document-server
cp .env.example .env
# Edit .env if needed
```
2. **Create documents directory**:
```bash
mkdir -p documents
# Add your work documents here
```
3. **Start the server**:
```bash
docker-compose up -d
```
4. **Test it**:
```bash
curl http://localhost:8000/health
```
### Option 2: Python Virtual Environment
1. **Setup**:
```bash
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
```
2. **Configure**:
```bash
cp .env.example .env
export $(cat .env | xargs)
```
3. **Run**:
```bash
python server.py
```
## Configuration
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_TRANSPORT` | `sse` | Transport type: `sse` (HTTP) or `stdio` |
| `MCP_HOST` | `0.0.0.0` | Server host (SSE only) |
| `MCP_PORT` | `8000` | Server port (SSE only) |
| `DOCUMENTS_PATH` | `/documents` | Path to documents directory |
| `MAX_FILE_SIZE_MB` | `10` | Maximum file size in MB |
| `ALLOWED_EXTENSIONS` | `.txt,.md,...` | Comma-separated allowed extensions |
### Docker Compose Volumes
Edit `docker-compose.yml` to mount your work documents:
```yaml
volumes:
# Option 1: Local directory
- ./documents:/documents:ro
# Option 2: Specific path
- /path/to/work/documents:/documents:ro
```
## Integration with Claude
### Via Claude Desktop (Local)
1. Edit Claude Desktop config (`~/.config/claude/mcp_servers.json` on Linux):
```json
{
"document-server": {
"command": "docker",
"args": ["exec", "-i", "mcp-document-server", "python", "server.py"],
"env": {
"MCP_TRANSPORT": "stdio"
}
}
}
```
### Via HTTP (Tailscale/Network)
If running on your home server and accessing via Tailscale:
1. Start server with SSE transport (default)
2. Note your Tailscale IP (e.g., `100.x.x.x`)
3. Access at `http://100.x.x.x:8000`
Configure Claude to use this URL in your MCP client settings.
## Available Tools
### 1. `list_documents`
List all documents in a directory.
**Parameters**:
- `subdirectory` (optional): Subdirectory to list
- `recursive` (optional): List recursively
**Example**:
```json
{
"subdirectory": "projects/2024",
"recursive": true
}
```
### 2. `read_document`
Read the contents of a specific document.
**Parameters**:
- `file_path`: Relative path to document
- `max_chars` (optional): Maximum characters to return (default: 50000)
**Example**:
```json
{
"file_path": "projects/2024/Q4-report.pdf",
"max_chars": 50000
}
```
### 3. `search_documents`
Search for documents containing specific text.
**Parameters**:
- `query`: Search query
- `file_extension` (optional): Filter by extension
- `case_sensitive` (optional): Case-sensitive search
**Example**:
```json
{
"query": "quarterly review",
"file_extension": ".docx",
"case_sensitive": false
}
```
## Security Considerations
### Path Traversal Protection
- All file access is restricted to `DOCUMENTS_PATH`
- Symbolic links are resolved and validated
- Path traversal attempts (../) are blocked
### Read-Only Access
- Server only reads files, never writes
- Docker container runs with read-only volume mount
- No file modification capabilities exposed
### File Type Restrictions
- Only allowed extensions can be accessed
- Binary files require appropriate parsers
- Unknown types are rejected
### Network Security
- Use Tailscale for encrypted access
- Consider adding authentication token
- Bind to localhost if only local access needed
## Tailscale Integration
### Setup
1. **On your home server**, ensure Tailscale is running:
```bash
sudo tailscale status
```
2. **Start MCP server**:
```bash
docker-compose up -d
```
3. **Get Tailscale IP**:
```bash
tailscale ip -4
```
4. **Access from anywhere**:
```
http://<your-tailscale-ip>:8000
```
### Firewall Rules
If using OPNsense with Tailscale:
1. Allow port 8000 on Tailscale interface
2. Add rule: `pass in on tailscale0 proto tcp from any to any port 8000`
## Advanced Configuration
### Custom Document Parsers
To add support for additional file types, modify `server.py`:
```python
elif full_path.suffix == '.custom':
# Your custom parser here
content = parse_custom_file(full_path)
```
### Authentication
Add basic token authentication:
1. Set `MCP_AUTH_TOKEN` in `.env`
2. Modify server to check token in requests
3. Pass token in Claude MCP client config
### Multiple Document Directories
Run multiple instances with different compose files:
```bash
# Work documents
docker-compose -f docker-compose.work.yml up -d
# Personal documents
docker-compose -f docker-compose.personal.yml up -d
```
## Troubleshooting
### Server won't start
```bash
# Check logs
docker-compose logs -f
# Verify documents directory exists
ls -la ./documents
# Check permissions
chmod 755 ./documents
```
### Cannot read files
```bash
# Verify file extensions are allowed
docker-compose exec mcp-document-server python -c \
"import os; print(os.getenv('ALLOWED_EXTENSIONS'))"
# Check file permissions
ls -la ./documents/
```
### Claude can't connect
```bash
# Test server is running
curl http://localhost:8000/health
# Check Tailscale connectivity
ping <tailscale-ip>
# Verify firewall rules
# On OPNsense, check Firewall > Rules > Tailscale
```
## Development
### Running Tests
```bash
# Install dev dependencies
pip install pytest pytest-asyncio
# Run tests
pytest tests/
```
### Debug Mode
```bash
# Enable debug logging
export LOG_LEVEL=DEBUG
python server.py
```
### Hot Reload
For development with auto-reload:
```bash
uvicorn server:mcp.app --reload --host 0.0.0.0 --port 8000
```
## Architecture
```
┌─────────────┐
│ Claude │
│ (claude.ai)│
└──────┬──────┘
│ MCP Protocol
│ (SSE/HTTP)
↓
┌─────────────────┐ ┌──────────────┐
│ MCP Document │─────→│ Documents │
│ Server │ │ Directory │
│ (Docker) │ │ (Read-Only) │
└─────────────────┘ └──────────────┘
│
│ Tailscale Network
│
┌─────────────────┐
│ Home Server │
│ (OPNsense) │
└─────────────────┘
```
## Contributing
This is a custom implementation for Aaron's needs, but feel free to adapt it for your own use.
## License
MIT License - See LICENSE file for details
## Support
For issues or questions:
- Check troubleshooting section
- Review Docker logs: `docker-compose logs -f`
- Verify network connectivity with Tailscale
---
**Built for**: Aaron Watson
**Integration**: Claude AI + Local Documents
**Stack**: Python, MCP SDK, Docker, FastAPI
