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:

   cd mcp-document-server cp .env.example .env # Edit .env if needed

2. Create documents directory:

   mkdir -p documents # Add your work documents here

3. Start the server:

   docker-compose up -d

4. Test it:

   curl http://localhost:8000/health

Option 2: Python Virtual Environment

1. Setup:

   python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -r requirements.txt

2. Configure:

   cp .env.example .env export $(cat .env | xargs)

3. Run:

   python server.py

Configuration

Environment Variables

Docker Compose Volumes

Edit docker-compose.yml to mount your work documents:

Integration with Claude

Via Claude Desktop (Local)

1. Edit Claude Desktop config (~/.config/claude/mcp_servers.json on Linux):

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:

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:

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:

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:

   sudo tailscale status

2. Start MCP server:

   docker-compose up -d

3. Get Tailscale IP:

   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:

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:

Troubleshooting

Server won't start

Cannot read files

Claude can't connect

Development

Running Tests

Debug Mode

Hot Reload

For development with auto-reload:

Architecture

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