MCP Document Server MCP Server

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:

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):

{
  "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:

{
  "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:

{
  "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:

{
  "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:

   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:

elif full_path.suffix == '.custom':
    # Your custom parser here
    content = parse_custom_file(full_path)