Qolaba MCP

支持MCP服务器🚀

一个Containerized 模型上下文协议（MCP）服务器 对于 AI API 支持将Qolaba的AI功能集成到Claude Desktop和其他MCP兼容的客户端中。

✨ 特性

• 🤖 多模型支持访问Gemini，Claude，GPT和其他型号
• 🌐 互联网搜索直接从Claude搜索
• 📚 RAG（检索增强生成）文档上传和智能搜索
• 💻 代码执行模型可以直接执行代码
• 🐳 Docker就绪： 完全包含健康检查
• 🔒 当然：非root用户、资源限制、环境基础秘密
• 📊 日志记录自动日志旋转和监控

📋 前提条件

• 安装 Docker 和 Docker Compose
• Qolaba AI Account API 访问注册)
• 本地使用： Claude Desktop （下载)

🚀 快速启动

1.知识库klonen

git clone https://github.com/YOUR_USERNAME/qolaba-mcp-server.git
cd qolaba-mcp-server

2. 设置环境变量

⚠️ 重要：这一步是 要求没有！ .env 文件无法启动容器 ！

创建一个 .env 模板文件 ：

cp .env.example .env

打开 .env 穿上你的 真实凭据 结束：

# Mit einem Editor deiner Wahl
nano .env
# oder
vim .env

死 .env 文件必须包含：

QOLABA_API_TOKEN=xxxxxxxxxxxxxxxxx
QOLABA_ORG_ID=xxxxxxxxxxxxxx

💡 获得凭据: 1. 进入 https://qolaba.ai/dashboard 1. 创建API令牌 1. 复制令牌和组织ID 1. 把它们放在 .env 文件一 ⚠️ 重要 - 凭据格式: - 代币: 只输入令牌，没有“qol_live\_”前缀 - 组织ID只需输入 ID，不要使用“org\_”前缀 - 例如：如果令牌是“qol_live_abc123”，请只输入“abc123”

3. 容器启动

docker-compose up -d

4. 检查状态

# Container-Logs anzeigen
docker-compose logs -f

# Container Health Status prüfen
docker ps | grep qolaba-mcp-server

# Detaillierter Health Check Status
docker inspect --format='{{.State.Health.Status}}' qolaba-mcp-server

# MCP Server Endpoint (SSE) testen
curl http://localhost:8003/sse

💡 提示容器在端口 8001 上有一个内部健康检查，由 Docker 自动监控。MCP SSE 服务器运行于端口 8000（外部为 8003）。

🔧 Claude桌面集成

有 两种方法要将 MCP 服务器连接到 Claude Desktop：

方法 1：HTTP/SSE 传输（推荐用于远程服务器）

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS） 或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "qolaba": {
      "url": "http://localhost:8003/sse"
    }
  }
}

替换远程服务器 localhost 你的服务器的IP。

方法2：Docker Exec + STDIO Transport（用于本地安装）

{
  "mcpServers": {
    "qolaba": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "qolaba-mcp-server",
        "python",
        "qolaba_server.py",
        "--transport",
        "stdio"
      ]
    }
  }
}

配置后 重新启动 Claude 桌面.

🌐 其他 MCP 兼容客户端

Qolaba MCP 服务器可以 多个客户同时 被使用！

Gemini CLI集成

Gemini CLI 的详细分步指南：

📖 Gemini CLI安装指南

快速配置 为 ~/.gemini/settings.json:

{
  "mcpServers": {
    "qolaba": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/client",
        "http://localhost:8003/sse"
      ]
    }
  }
}

其他 MCP 客户端

服务器通过以下方式支持所有 MCP 兼容的客户端：

• HTTP/SSE: http://localhost:8003/sse
• 工作室: docker exec -i qolaba-mcp-server python /app/qolaba_server.py

🛠️ 可用工具

MCP 服务器提供以下工具：

1. qolaba_chat

与不同的AI模型聊天。

参数：

• prompt （string）： 您的讯息/问题
• model （字符串，可选）：模型ID（标准： gemini-1.5-flash)
• internet_search （bool， optional）： 启用 Web 搜索 （默认： false)
• code_execution （bool， optional） 允许代码执行（默认： false)
• rag （bool， optional）：使用上传的文档（默认： false)
• temperature （float，可选）：创造力0.0-1.0（默认： 0.7)
• max_tokens （int，可选）：最大响应长度（默认： 2048)

例如：

Verwende qolaba_chat mit dem Prompt "Was ist Quantencomputing?" und aktiviere internet_search

2. qolaba_list_models

列出所有可用型号。

例如：

Zeige mir alle verfügbaren Qolaba Modelle

3. qolaba_upload_document

将文档上传到 RAG 的 Vector Store。

参数：

• file_path （string） 文件路径
• document_name （string， optional） 文件名称
• metadata （dict， optional）： 其他元数据

支持的格式： PDF、CSV、TXT、DOC、DOCX

例如：

Lade das Dokument /path/to/document.pdf in Qolaba hoch

4. qolaba_search

使用 AI 摘要执行 Web 搜索。

参数：

• query （string）： 搜索
• model （string， optional） 摘要模型
• max_results （int， optional）： 结果数量 （默认： 5)

例如：

Suche im Internet nach "neueste KI Entwicklungen 2024"

📦 在 NAS 上部署门户

对于初学者：一步一步的指导

步骤1：打开门户

1. 打开浏览器
2. 转到您的门户网址（例如： http://192.168.1.100:9000)
3. 登录

步骤2：创建堆栈

1. 在菜单中左键单击 “堆叠”
2. 点击右上角 “+添加堆栈”
3. 给堆栈命名： qolaba-mcp

步骤 3：插入 Docker Compose

1. 选择 “Web编辑器”
2. 复制完整内容 docker-compose.yml 到文本框
3. 向下滚动 “环境变量”

步骤4：设置环境变量

点击 “+添加环境变量” 并添加：

⚠️ 重要： 将值替换为您的真实凭据 qolaba.ai/仪表板

步骤 5：部署 Stack

1. 向下滚动
2. 点击 “部署堆栈”
3. 等待状态显示“运行”（约30-60秒）

步骤6：检查

1. 点击堆栈名称 qolaba-mcp
2. 你需要一个容器。 qolaba-mcp-server mit状态 “正在运行” 查看
3. 点击容器
4. 点击 “日志” 查看支出

步骤7：测试

1. 在 Portainer 中，查看容器状态。它应该 “健康” 在绿色符号旁边。

1. 点击容器，然后点击 “日志”你应该看到：

   Starting Qolaba MCP Server in http mode
   Health Check Server läuft auf Port 8001
   Using HTTP transport on 0.0.0.0:8000

1. 在浏览器或终端中测试 MCP SSE 端点：

   curl http://DEINE_NAS_IP:8003/sse

✅ 如果容器状态为“健康”，并且日志没有显示错误，那么一切都可以！

替代方案：基于存储库的部署

如果您的 NAS 有直接的 Git 访问权限：

1. 在Portainer： 堆栈 → +添加堆栈
2. 选择 “存储库”
3. 输入 ：

- 仓库地址: https://github.com/YOUR_USERNAME/qolaba-mcp-server - 撰写路径: docker-compose.yml - 环境变量如上所述

1. 点击 “部署堆栈”

🔍 故障排除

❌ 容器startet nicht-“必须设置QOLABA_API_TOKEN”

问题：死亡 .env 文件不存在或为空 。

解决方案:

# 1. Prüfe ob .env Datei existiert
ls -la | grep .env

# Sollte zeigen:
# -rw-r--r-- 1 user user  xxx .env         <-- muss existieren!
# -rw-r--r-- 1 user user  xxx .env.example

# 2. Falls .env fehlt:
cp .env.example .env

# 3. Bearbeite .env und trage echte Credentials ein
nano .env

# 4. Validiere .env Inhalt
cat .env
# Sollte zeigen:
# QOLABA_API_TOKEN=qol_live_...
# QOLABA_ORG_ID=org_...

# 5. Container neu starten
docker compose down
docker compose up -d

❌ 容器启动，但API返回401未授权

问题验证错误，尽管仪表板上的凭据正确。

乌尔萨奇无效的凭据格式 .env 文件 。

解决方案:

# Prüfe deine .env Datei
cat .env

# ❌ FALSCH - Mit Prefixes:
QOLABA_API_TOKEN=qol_live_abc123xyz
QOLABA_ORG_ID=org_abc123xyz

# ✅ RICHTIG - Ohne Prefixes:
QOLABA_API_TOKEN=abc123xyz
QOLABA_ORG_ID=abc123xyz

重要删除前缀 qol_live_ 和 org_ 凭证！

修正后：

docker compose down
docker compose up -d

容器启动但“不健康”

# Logs anzeigen
docker compose logs qolaba-mcp

# Container Status prüfen
docker ps -a | grep qolaba

# Health Status prüfen
docker inspect --format='{{.State.Health.Status}}' qolaba-mcp-server

常见问题：

• ❌ 凭据错误检查仪表板和格式上的令牌和组织ID（没有前缀！）
• ❌ 端口已占用更改 8003 在 docker-compose.yml
• ❌ 健康检查失败等待 30 秒，然后重新检查

API错误

# Container Health Status prüfen
docker inspect --format='{{.State.Health.Status}}' qolaba-mcp-server

# Container Logs prüfen
docker-compose logs qolaba-mcp-server | tail -20

如果容器不健康或出现凭据错误：

• 检查 .env 文件（必须设置 QOLABA_API_TOKEN 和 QOLABA_ORG_ID）
• 重新启动容器 ： docker-compose restart
• 检查日志为“credentials_configured: false”

Claude Desktop 无法连接

1. 检查配置文件路径 ：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json

1. JSON语法有效性：

   # macOS/Linux
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python -m json.tool

1. 完全重新启动 Claude Desktop （不仅关闭窗户）

1. 检查日志 ：

   docker-compose logs -f

孔弗利克特港

如果端口 8003 已占用：

# In docker-compose.yml ändern
ports:
  - "8004:8000"  # Ändere 8003 zu 8004 (oder einen freien Port)

重新启动容器 ：

docker-compose down
docker-compose up -d

📊 监控

显示日志

# Alle Logs
docker-compose logs -f

# Nur letzte 50 Zeilen
docker-compose logs --tail=50 qolaba-mcp

# Log-Datei im Container
docker exec qolaba-mcp-server tail -f /app/logs/qolaba_mcp.log

资源使用

# CPU/Memory Stats
docker stats qolaba-mcp-server

# Container Infos
docker inspect qolaba-mcp-server

健康检查

# Container Health Status
docker inspect --format='{{.State.Health.Status}}' qolaba-mcp-server

# Health Check Details
docker inspect --format='{{json .State.Health}}' qolaba-mcp-server | python -m json.tool

# Direkter Health Check im Container (nur intern verfügbar)
docker exec qolaba-mcp-server curl -s http://localhost:8001/health

🔒 安全

最佳实践

✅ 已转换 ：

• 容器以非 root 用户身份运行（mcpuser)
• 关于环境变量的秘密（不在代码中）
• 资源限制（最大512MB RAM，1个CPU）
• 健康检查监测
• 日志旋转（每个文件最多10MB，3个文件）
• 最小基础映像（python:3.11-slim）

⚠️ 另外推荐：

• 使用 HTTPS 的反向代理（例如 Traffic、Nginx）
• 端口 8003 防火墙规则
• 定期更新： docker-compose pull && docker-compose up -d

🔄 更新

更新服务器

# Code pullen
git pull origin main

# Container neu bauen und starten
docker-compose up -d --build

# Alte Images aufräumen
docker image prune -f

在波提纳

1. 进入 堆栈 → qolaba-mcp
2. 点击 “更新堆栈” （如果是repository）
3. 或者： 点击 “编辑”更改配置，点击 “更新堆栈”

📚 更多资源

• Qolaba人工智能文档
• 模型上下文协议规格
• FastMCP框架
• 克劳德桌面

🤝 支持

遇到问题：

1. 检查 故障排除 部分
2. 检查日志： docker-compose logs
3. 在 GitHub 上创建问题：

- 错误描述 - 日志（没有凭据！） - 系统信息（操作系统、Docker版本）

📝 许可证

麻省理工学院执照 许可证 文件

______________________________________________________________________

创建于❤️ Claude & Qolaba 社区