AI导哈

文档访问服务器

一个安全的模型上下文协议（MCP）服务器，为Claude AI提供对本地文档的访问，支持多种文件格式和全文搜索。

  • by watsona4
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 watsona4/mcp-document-server

使用说明

MCP文档服务器

一个安全的模型上下文协议（MCP）服务器，为Claude AI提供对本地文档的访问。专为Aaron的工作文档集成需求而构建。

特性

  • 🔒 安全：具有路径遍历保护的只读访问
  • 📁 文件支持：PDF、DOCX、XLSX、PPTX、TXT、MD、JSON、YAML、CSV、LOG
  • 🔍 搜索：跨文档的全文搜索
  • 🐳 码头工人：使用Docker Compose轻松部署
  • 🌐 网络：通过HTTP（SSE）或本地STDIO工作
  • 🔌 尾秤就绪：与您现有的Tailscale网络集成

快速开始

选项1:Docker Compose（推荐）

  1. 克隆和设置:

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

  2. 创建文档目录:

    mkdir -p documents
# Add your work documents here

  3. 启动服务器:

    docker-compose up -d

  4. 测试它:

    curl http://localhost:8000/health

选项2:Python虚拟环境

  1. 设置:

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

  2. 配置:

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

  3. 跑:

    python server.py

配置

环境变量

变量 默认值 描述
MCP_TRANSPORT sse 运输类型： sse （HTTP）或 stdio
MCP_HOST 0.0.0.0 服务器主机（仅限SSE）
MCP_PORT 8000 服务器端口（仅限SSE）
DOCUMENTS_PATH /documents 文档目录路径
MAX_FILE_SIZE_MB 10 最大文件大小（MB）
ALLOWED_EXTENSIONS .txt,.md,... 逗号分隔的允许扩展名

Docker编写卷

编辑 docker-compose.yml 要装载工作文档，请执行以下操作：

volumes:
  # Option 1: Local directory
  - ./documents:/documents:ro
  
  # Option 2: Specific path
  - /path/to/work/documents:/documents:ro

与Claude整合

通过克劳德桌面（本地）

  1. 编辑Claude桌面配置(~/.config/claude/mcp_servers.json 在Linux上）：
{
  "document-server": {
    "command": "docker",
    "args": ["exec", "-i", "mcp-document-server", "python", "server.py"],
    "env": {
      "MCP_TRANSPORT": "stdio"
    }
  }
}

通过HTTP（尾标/网络）

如果在家庭服务器上运行并通过Tailscale访问：

  1. 使用SSE传输启动服务器（默认）
  2. 注意您的Tailscale IP（例如。， 100.x.x.x)
  3. 访问地址： http://100.x.x.x:8000

将Claude配置为在MCP客户端设置中使用此URL。

可用工具

1. list_documents

列出目录中的所有文档。

参数:

  • subdirectory （可选）：要列出的子目录
  • recursive （可选）：递归列表

示例:

{
  "subdirectory": "projects/2024",
  "recursive": true
}

2. read_document

阅读特定文档的内容。

参数:

  • file_path：文档的相对路径
  • max_chars （可选）：返回的最大字符数（默认值：50000）

示例:

{
  "file_path": "projects/2024/Q4-report.pdf",
  "max_chars": 50000
}

3. search_documents

搜索包含特定文本的文档。

参数:

  • query：搜索查询
  • file_extension （可选）：按扩展名筛选
  • case_sensitive （可选）：区分大小写的搜索

示例:

{
  "query": "quarterly review",
  "file_extension": ".docx",
  "case_sensitive": false
}

安全考虑

路径横向保护

  • 所有文件访问权限仅限于 DOCUMENTS_PATH
  • 符号链接已解析并验证
  • 路径遍历尝试（../）被阻止

只读访问

  • 服务器只读取文件，从不写入
  • Docker容器以只读卷挂载方式运行
  • 没有公开文件修改功能

文件类型限制

  • 只能访问允许的扩展名
  • 二进制文件需要适当的解析器
  • 未知类型被拒绝

网络安全

  • 使用Tailscale进行加密访问
  • 考虑添加身份验证令牌
  • 如果只需要本地访问，则绑定到localhost

Tailscale集成

设置

  1. 在您的家庭服务器上，确保Tailscale正在运行：

    sudo tailscale status

  2. 启动MCP服务器:

    docker-compose up -d

  3. 获取Tailscale IP:

    tailscale ip -4

  4. 从任何地方访问:

    http://<your-tailscale-ip>:8000

防火墙规则

如果将OPNsense与Tailscale一起使用：

  1. 在Tailscale接口上允许端口8000
  2. 添加规则： pass in on tailscale0 proto tcp from any to any port 8000

高级配置

自定义文档分析器

要添加对其他文件类型的支持，请修改 server.py:

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

认证

添加基本令牌身份验证：

  1. 集 MCP_AUTH_TOKEN 在 .env
  2. 修改服务器以检查请求中的令牌
  3. Claude MCP客户端配置中的传递令牌

多个文档目录

使用不同的编写文件运行多个实例：

# Work documents
docker-compose -f docker-compose.work.yml up -d

# Personal documents
docker-compose -f docker-compose.personal.yml up -d

故障排除

服务器无法启动

# Check logs
docker-compose logs -f

# Verify documents directory exists
ls -la ./documents

# Check permissions
chmod 755 ./documents

无法读取文件

# 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/

克劳德无法连接

# Test server is running
curl http://localhost:8000/health

# Check Tailscale connectivity
ping <tailscale-ip>

# Verify firewall rules
# On OPNsense, check Firewall > Rules > Tailscale

发展

运行测试

# Install dev dependencies
pip install pytest pytest-asyncio

# Run tests
pytest tests/

调试模式

# Enable debug logging
export LOG_LEVEL=DEBUG
python server.py

热重新加载

对于自动重新加载的开发：

uvicorn server:mcp.app --reload --host 0.0.0.0 --port 8000

建筑

┌─────────────┐
│   Claude    │
│  (claude.ai)│
└──────┬──────┘
       │ MCP Protocol
       │ (SSE/HTTP)
       ↓
┌─────────────────┐      ┌──────────────┐
│  MCP Document   │─────→│  Documents   │
│     Server      │      │  Directory   │
│   (Docker)      │      │ (Read-Only)  │
└─────────────────┘      └──────────────┘
       │
       │ Tailscale Network
       │
┌─────────────────┐
│  Home Server    │
│  (OPNsense)     │
└─────────────────┘

贡献

这是一个满足Aaron需求的自定义实现，但您可以随意对其进行调整以供自己使用。

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于问题或疑问：

  • 检查故障排除部分
  • 查看Docker日志： docker-compose logs -f
  • 使用Tailscale验证网络连接

专为：亚伦·沃森
整合：Claude AI+本地文档
堆栈：Python、MCP SDK、Docker、FastAPI

相关 MCP