MCP Homelab

MCP家庭实验室

用于家庭实验室与Perplexity AI集成的MCP服务器设置-提供文件系统访问和命令执行功能。

概述

此项目使 困惑AI 通过模型上下文协议（MCP）服务器安全访问您的家庭实验室。它提供：

• 📁 文件系统访问：在允许的目录（点文件、配置、工作区）中读/写文件
• 💻 命令执行：白名单系统和Docker命令的安全执行
• 🌐 远程访问：用于与Perplexity的远程MCP支持集成的HTTP网关
• 🔒 安全：路径限制和命令白名单

快速开始

先决条件

• Docker&Docker编写
• Nginx代理管理器（或类似的反向代理）
• 具有SSL证书的域

部署

# Clone the repository
git clone https://github.com/gauravahujame/mcp-homelab.git
cd mcp-homelab

# Start the services
chmod +x start-poc.sh
./start-poc.sh

反向代理设置

添加到Nginx代理管理器：

• 领域: mcp.yourdomain.com
• 转发到: your-docker-host-ip:3000
• 安全套接层：使用Let’s Encrypt启用
• WebSocket支持: ✅ 启用

困惑整合

1. 打开困惑（Mac应用程序）
2. 首选 设置 → 连接器 → 添加连接器
3. 选择 高级 远程MCP选项卡
4. 添加URL: https://mcp.yourdomain.com
5. 测试：“列出我工作区目录中的文件”

建筑

Perplexity AI → HTTPS → Nginx Proxy → Gateway:3000 → MCP Servers
                                           ├─ Filesystem:3001
                                           └─ Shell:3002

服务

文件结构

mcp-homelab/
├── docker-compose.yml      # Main orchestration
├── start-poc.sh           # Quick deployment script
├── filesystem/
│   └── start.sh          # Filesystem MCP startup
├── gateway/
│   ├── package.json      # HTTP gateway dependencies
│   └── server.js         # HTTP-to-MCP bridge
└── shell/
    ├── package.json      # Shell service dependencies
    └── server.js         # Safe command execution

安全特性

文件系统访问

• 路径限制：只能访问允许的目录

- ~/.config （只读） - ~/.dotfiles （只读） - ~/workspace （读写）

命令执行

• 仅限白名单：预定义的安全命令

- docker ps, docker images - systemctl status docker - df -h, free -m, uptime

• 超时保护：10秒执行限制
• 错误处理：安全的错误响应

示例用法

一旦与Perplexity集成，您可以：

💬 "Show me my current Docker containers"
💬 "List files in my workspace directory"
💬 "What's in my .zshrc file?"
💬 "Check system disk usage"
💬 "Create a new docker-compose.yml for nginx"

发展

添加新命令

编辑 shell/server.js 并添加到 ALLOWED_COMMANDS:

const ALLOWED_COMMANDS = [
  'docker ps',
  // Add your command here
  'your-new-command'
];

添加新路径

编辑 filesystem/start.sh 以包含其他目录：

exec npx @modelcontextprotocol/server-filesystem \
  --host 0.0.0.0 \
  --port 3001 \
  /allowed/config \
  /allowed/dotfiles \
  /allowed/workspace \
  /allowed/your-new-path

故障排除

服务未启动

# Check logs
docker-compose logs -f

# Restart services
docker-compose down && docker-compose up -d

困惑连接问题

1. 验证HTTPS证书是否有效
2. 检查WebSocket支持是否已启用
3. 手动测试终点： curl https://mcp.yourdomain.com/health

权限错误

# Fix script permissions
chmod +x filesystem/start.sh start-poc.sh

# Check Docker socket access
ls -la /var/run/docker.sock

贡献

1. 分叉存储库
2. 创建要素分支
3. 在本地测试您的更改
4. 提交拉取请求

许可证

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

链接

• 模型上下文协议文档
• 困惑MCP集成指南
• 官方MCP文件系统服务器